From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/stdlib/doc/src/supervisor_bridge.xml | 162 +++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 lib/stdlib/doc/src/supervisor_bridge.xml (limited to 'lib/stdlib/doc/src/supervisor_bridge.xml') 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 @@ + + + + +
+ + 1996 + 2007 + Ericsson AB, All Rights Reserved + + + 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. + + + supervisor_bridge + + + + +
+ supervisor_bridge + Generic Supervisor Bridge Behaviour. + +

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 OTP Design Principles + for more information.

+

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.

+

The sys module can be used for debugging a + supervisor_bridge.

+

Unless otherwise stated, all functions in this module will fail if + the specified supervisor_bridge does not exist or if bad arguments are + given.

+ + + + start_link(Module, Args) -> Result + start_link(SupBridgeName, Module, Args) -> Result + Create a supervisor bridge process. + + SupBridgeName = {local,Name} | {global,Name} +  Name = atom() + Module = atom() + Args = term() + Result = {ok,Pid} | ignore | {error,Error} +  Pid = pid() +  Error = {already_started,Pid} | term() + + +

Creates a supervisor_bridge process, linked to the calling + process, which calls Module:init/1 to start the subsystem. + To ensure a synchronized start-up procedure, this function does + not return until Module:init/1 has returned.

+

If SupBridgeName={local,Name} the supervisor_bridge is + registered locally as Name using register/2. + If SupBridgeName={global,Name} the supervisor_bridge is + registered globally as Name using + global:register_name/2. + If no name is provided, the supervisor_bridge is not registered. + If there already exists a process with the specified + SupBridgeName the function returns + {error,{already_started,Pid}}, where Pid is the pid + of that process.

+

Module is the name of the callback module.

+

Args is an arbitrary term which is passed as the argument + to Module:init/1.

+

If the supervisor_bridge and the subsystem are successfully + started the function returns {ok,Pid}, where Pid is + is the pid of the supervisor_bridge.

+

If Module:init/1 returns ignore, this function + returns ignore as well and the supervisor_bridge terminates + with reason normal. + If Module:init/1 fails or returns an error tuple or an + incorrect value, this function returns {error,Term} where + Term is a term with information about the error, and + the supervisor_bridge terminates with reason Term.

+ + + + +
+ CALLBACK FUNCTIONS +

The following functions should be exported from a + supervisor_bridge callback module.

+
+ + + Module:init(Args) -> Result + Initialize process and start subsystem. + + Args = term() + Result = {ok,Pid,State} | ignore | {error,Error} +  Pid = pid() +  State = term() +  Error = term() + + +

Whenever a supervisor_bridge is started using + supervisor_bridge:start_link/2,3, this function is called + by the new process to start the subsystem and initialize.

+

Args is the Args argument provided to the start + function.

+

The function should return {ok,Pid,State} where Pid + is the pid of the main process in the subsystem and State + is any term.

+

If later Pid terminates with a reason Reason, + the supervisor bridge will terminate with reason Reason as + well. + If later the supervisor_bridge is stopped by its supervisor with + reason Reason, it will call + Module:terminate(Reason,State) to terminate.

+

If something goes wrong during the initialization the function + should return {error,Error} where Error is any + term, or ignore.

+ + + + Module:terminate(Reason, State) + Clean up and stop subsystem. + + Reason = shutdown | term() + State = term() + + +

This function is called by the supervisor_bridge when it is about + to terminate. It should be the opposite of Module:init/1 + and stop the subsystem and do any necessary cleaning up. + The return value is ignored.

+

Reason is shutdown 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 Term, + Reason will be Term.

+

State is taken from the return value of + Module:init/1.

+ + + + +
+ SEE ALSO +

supervisor(3), + sys(3)

+
+ + -- cgit v1.2.3