1supervisor_bridge(3)       Erlang Module Definition       supervisor_bridge(3)
2
3
4

NAME

6       supervisor_bridge - Generic supervisor bridge behavior.
7

DESCRIPTION

9       This  behavior module provides a supervisor bridge, a process that con‐
10       nects a subsystem not designed according to the OTP  design  principles
11       to  a supervision tree. The supervisor bridge sits between a supervisor
12       and the subsystem. It behaves like a real supervisor to its own  super‐
13       visor, but has a different interface than a real supervisor to the sub‐
14       system. For more information, see  Supervisor Behaviour in  OTP  Design
15       Principles.
16
17       A supervisor bridge assumes the functions for starting and stopping the
18       subsystem to be located in a callback module exporting a predefined set
19       of functions.
20
21       The sys(3) module can be used for debugging a supervisor bridge.
22
23       Unless otherwise stated, all functions in this module fail if the spec‐
24       ified supervisor bridge does not exist or if bad arguments  are  speci‐
25       fied.
26

EXPORTS

28       start_link(Module, Args) -> Result
29
30       start_link(SupBridgeName, Module, Args) -> Result
31
32              Types:
33
34                 SupBridgeName = {local, Name} | {global, Name}
35                 Name = atom()
36                 Module = module()
37                 Args = term()
38                 Result = {ok, Pid} | ignore | {error, Error}
39                 Error = {already_started, Pid} | term()
40                 Pid = pid()
41
42              Creates  a  supervisor  bridge  process,  linked  to the calling
43              process, which calls Module:init/1 to start  the  subsystem.  To
44              ensure  a synchronized startup procedure, this function does not
45              return until Module:init/1 has returned.
46
47                * If SupBridgeName={local,Name}, the supervisor bridge is reg‐
48                  istered locally as Name using register/2.
49
50                * If  SupBridgeName={global,Name},  the  supervisor  bridge is
51                  registered globally as Name using global:register_name/2.
52
53                * If SupBridgeName={via,Module,Name}, the supervisor bridge is
54                  registered  as  Name using a registry represented by Module.
55                  The Module callback is to export functions  register_name/2,
56                  unregister_name/1,  and send/2, which are to behave like the
57                  corresponding functions in global. Thus, {via,global,Global‐
58                  Name} is a valid reference.
59
60              If no name is provided, the supervisor bridge is not registered.
61
62              Module is the name of the callback module.
63
64              Args is an arbitrary term that is passed as the argument to Mod‐
65              ule:init/1.
66
67                * If the supervisor bridge and the subsystem are  successfully
68                  started,  the function returns {ok,Pid}, where Pid is is the
69                  pid of the supervisor bridge.
70
71                * If there already exists a process with  the  specified  Sup‐
72                  BridgeName,           the          function          returns
73                  {error,{already_started,Pid}}, where Pid is the pid of  that
74                  process.
75
76                * If  Module:init/1  returns  ignore,  this  function  returns
77                  ignore as well and the  supervisor  bridge  terminates  with
78                  reason normal.
79
80                * If  Module:init/1  fails  or  returns  an  error tuple or an
81                  incorrect value, this function returns {error,Errorr}, where
82                  Error  is  a  term with information about the error, and the
83                  supervisor bridge terminates with reason Error.
84

CALLBACK FUNCTIONS

86       The following functions must be exported from a supervisor_bridge call‐
87       back module.
88

EXPORTS

90       Module:init(Args) -> Result
91
92              Types:
93
94                 Args = term()
95                 Result = {ok,Pid,State} | ignore | {error,Error}
96                  Pid = pid()
97                  State = term()
98                  Error = term()
99
100              Whenever  a  supervisor  bridge is started using start_link/2,3,
101              this function is called by the new process to start the  subsys‐
102              tem and initialize.
103
104              Args is the Args argument provided to the start function.
105
106              The  function  is to return {ok,Pid,State}, where Pid is the pid
107              of the main process in the subsystem and State is any term.
108
109              If later Pid terminates with a  reason  Reason,  the  supervisor
110              bridge  terminates  with  reason  Reason  as  well. If later the
111              supervisor bridge is stopped by its supervisor with reason  Rea‐
112              son, it calls Module:terminate(Reason,State) to terminate.
113
114              If   the   initialization  fails,  the  function  is  to  return
115              {error,Error}, where Error is any term, or ignore.
116
117       Module:terminate(Reason, State)
118
119              Types:
120
121                 Reason = shutdown | term()
122                 State = term()
123
124              This function is called by the  supervisor  bridge  when  it  is
125              about  to  terminate.  It is to be the opposite of Module:init/1
126              and stop the subsystem and do any  necessary  cleaning  up.  The
127              return value is ignored.
128
129              Reason is shutdown if the supervisor bridge is terminated by its
130              supervisor. If the supervisor  bridge  terminates  because  a  a
131              linked  process  (apart  from the main process of the subsystem)
132              has terminated with reason Term, then Reason becomes Term.
133
134              State is taken from the return value of Module:init/1.
135

SEE ALSO

137       supervisor(3), sys(3)
138
139
140
141Ericsson AB                     stdlib 3.4.5.1            supervisor_bridge(3)
Impressum