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.
Functions
start_link(Module, Args) -> Result
start_link(SupBridgeName, Module, Args) -> Result
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.
Functions
Module:init(Args) -> Result
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)
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
.