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)

Ericsson AB                                       stdlib 1.19.4                          supervisor_bridge(3erl)