aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/supervisor_bridge.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc/src/supervisor_bridge.xml')
-rw-r--r--lib/stdlib/doc/src/supervisor_bridge.xml162
1 files changed, 162 insertions, 0 deletions
diff --git a/lib/stdlib/doc/src/supervisor_bridge.xml b/lib/stdlib/doc/src/supervisor_bridge.xml
new file mode 100644
index 0000000000..b334f57caf
--- /dev/null
+++ b/lib/stdlib/doc/src/supervisor_bridge.xml
@@ -0,0 +1,162 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1996</year>
+ <year>2007</year>
+ <holder>Ericsson AB, All Rights Reserved</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>supervisor_bridge</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>supervisor_bridge</module>
+ <modulesummary>Generic Supervisor Bridge Behaviour.</modulesummary>
+ <description>
+ <p>A behaviour module for implementing a supervisor_bridge, a process
+ which connects a subsystem not designed according to the OTP design
+ principles to a supervision tree. The supervisor_bridge sits between
+ a supervisor and the subsystem. It behaves like a real supervisor to
+ its own supervisor, but has a different interface than a real
+ supervisor to the subsystem. Refer to <em>OTP Design Principles</em>
+ for more information.</p>
+ <p>A supervisor_bridge assumes the functions for starting and stopping
+ the subsystem to be located in a callback module exporting a
+ pre-defined set of functions.</p>
+ <p>The <c>sys</c> module can be used for debugging a
+ supervisor_bridge.</p>
+ <p>Unless otherwise stated, all functions in this module will fail if
+ the specified supervisor_bridge does not exist or if bad arguments are
+ given.</p>
+ </description>
+ <funcs>
+ <func>
+ <name>start_link(Module, Args) -> Result</name>
+ <name>start_link(SupBridgeName, Module, Args) -> Result</name>
+ <fsummary>Create a supervisor bridge process.</fsummary>
+ <type>
+ <v>SupBridgeName = {local,Name} | {global,Name}</v>
+ <v>&nbsp;Name = atom()</v>
+ <v>Module = atom()</v>
+ <v>Args = term()</v>
+ <v>Result = {ok,Pid} | ignore | {error,Error}</v>
+ <v>&nbsp;Pid = pid()</v>
+ <v>&nbsp;Error = {already_started,Pid} | term()</v>
+ </type>
+ <desc>
+ <p>Creates a supervisor_bridge process, linked to the calling
+ process, which calls <c>Module:init/1</c> to start the subsystem.
+ To ensure a synchronized start-up procedure, this function does
+ not return until <c>Module:init/1</c> has returned.</p>
+ <p>If <c>SupBridgeName={local,Name}</c> the supervisor_bridge is
+ registered locally as <c>Name</c> using <c>register/2</c>.
+ If <c>SupBridgeName={global,Name}</c> the supervisor_bridge is
+ registered globally as <c>Name</c> using
+ <c>global:register_name/2</c>.
+ If no name is provided, the supervisor_bridge is not registered.
+ If there already exists a process with the specified
+ <c>SupBridgeName</c> the function returns
+ <c>{error,{already_started,Pid}}</c>, where <c>Pid</c> is the pid
+ of that process.</p>
+ <p><c>Module</c> is the name of the callback module.</p>
+ <p><c>Args</c> is an arbitrary term which is passed as the argument
+ to <c>Module:init/1</c>.</p>
+ <p>If the supervisor_bridge and the subsystem are successfully
+ started the function returns <c>{ok,Pid}</c>, where <c>Pid</c> is
+ is the pid of the supervisor_bridge.</p>
+ <p>If <c>Module:init/1</c> returns <c>ignore</c>, this function
+ returns <c>ignore</c> as well and the supervisor_bridge terminates
+ with reason <c>normal</c>.
+ If <c>Module:init/1</c> fails or returns an error tuple or an
+ incorrect value, this function returns <c>{error,Term}</c> where
+ <c>Term</c> is a term with information about the error, and
+ the supervisor_bridge terminates with reason <c>Term</c>.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>CALLBACK FUNCTIONS</title>
+ <p>The following functions should be exported from a
+ <c>supervisor_bridge</c> callback module.</p>
+ </section>
+ <funcs>
+ <func>
+ <name>Module:init(Args) -> Result</name>
+ <fsummary>Initialize process and start subsystem.</fsummary>
+ <type>
+ <v>Args = term()</v>
+ <v>Result = {ok,Pid,State} | ignore | {error,Error}</v>
+ <v>&nbsp;Pid = pid()</v>
+ <v>&nbsp;State = term()</v>
+ <v>&nbsp;Error = term()</v>
+ </type>
+ <desc>
+ <p>Whenever a supervisor_bridge is started using
+ <c>supervisor_bridge:start_link/2,3</c>, this function is called
+ by the new process to start the subsystem and initialize.</p>
+ <p><c>Args</c> is the <c>Args</c> argument provided to the start
+ function.</p>
+ <p>The function should return <c>{ok,Pid,State}</c> where <c>Pid</c>
+ is the pid of the main process in the subsystem and <c>State</c>
+ is any term.</p>
+ <p>If later <c>Pid</c> terminates with a reason <c>Reason</c>,
+ the supervisor bridge will terminate with reason <c>Reason</c> as
+ well.
+ If later the supervisor_bridge is stopped by its supervisor with
+ reason <c>Reason</c>, it will call
+ <c>Module:terminate(Reason,State)</c> to terminate.</p>
+ <p>If something goes wrong during the initialization the function
+ should return <c>{error,Error}</c> where <c>Error</c> is any
+ term, or <c>ignore</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>Module:terminate(Reason, State)</name>
+ <fsummary>Clean up and stop subsystem.</fsummary>
+ <type>
+ <v>Reason = shutdown | term()</v>
+ <v>State = term()</v>
+ </type>
+ <desc>
+ <p>This function is called by the supervisor_bridge when it is about
+ to terminate. It should be the opposite of <c>Module:init/1</c>
+ and stop the subsystem and do any necessary cleaning up.
+ The return value is ignored.</p>
+ <p><c>Reason</c> is <c>shutdown</c> if the supervisor_bridge is
+ terminated by its supervisor. If the supervisor_bridge terminates
+ because a a linked process (apart from the main process of
+ the subsystem) has terminated with reason <c>Term</c>,
+ <c>Reason</c> will be <c>Term</c>.</p>
+ <p><c>State</c> is taken from the return value of
+ <c>Module:init/1</c>.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>SEE ALSO</title>
+ <p><seealso marker="supervisor">supervisor(3)</seealso>,
+ <seealso marker="sys">sys(3)</seealso></p>
+ </section>
+</erlref>
+