diff options
Diffstat (limited to 'lib/stdlib/doc/src/supervisor_bridge.xml')
| -rw-r--r-- | lib/stdlib/doc/src/supervisor_bridge.xml | 162 |
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> Name = atom()</v> + <v>Module = atom()</v> + <v>Args = term()</v> + <v>Result = {ok,Pid} | ignore | {error,Error}</v> + <v> Pid = pid()</v> + <v> 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> Pid = pid()</v> + <v> State = term()</v> + <v> 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> + |