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)