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

CALLBACK FUNCTIONS

89       The following functions must be exported from a supervisor_bridge call‐
90       back module.
91

EXPORTS

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

SEE ALSO

140       supervisor(3), sys(3)
141
142
143
144Ericsson AB                       stdlib 4.2              supervisor_bridge(3)
Impressum