trusty (3) supervisor_bridge.3erl.gz

NAME

       supervisor_bridge - Generic Supervisor Bridge Behaviour.

DESCRIPTION

       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.

EXPORTS

       start_link(Module, Args) -> Result

       start_link(SupBridgeName, Module, Args) -> Result

              Types:

                 SupBridgeName = {local, Name} | {global, Name}
                 Name = atom()
                 Module = module()
                 Args = term()
                 Result = {ok, Pid} | ignore | {error, Error}
                 Error = {already_started, Pid} | term()
                 Pid = pid()

              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   SupBridgeName={via,Module,Name}  the  supervisor_bridge  is
              registered as Name using a registry represented by Module. The Module callback should  export  the
              functions   register_name/2,   unregister_name/1   and   send/2,  which  should  behave  like  the
              corresponding functions in global. Thus, {via,global,GlobalName} is a valid reference. 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,Errorr} where Error is  a  term  with  information  about  the
              error, and the supervisor_bridge terminates with reason Error.

CALLBACK FUNCTIONS

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

EXPORTS

       Module:init(Args) -> Result

              Types:

                 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)

              Types:

                 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(3erl), sys(3erl)