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     {error,{al‐
73                  ready_started,Pid}}, where Pid is the pid of that process.
74
75                * If Module:init/1 returns ignore, this function  returns  ig‐
76                  nore  as well and the supervisor bridge terminates with rea‐
77                  son normal.
78
79                * If Module:init/1 fails or returns an error tuple or  an  in‐
80                  correct  value,  this function returns {error,Errorr}, where
81                  Error is a term with information about the  error,  and  the
82                  supervisor bridge terminates with reason Error.
83

CALLBACK FUNCTIONS

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

EXPORTS

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

SEE ALSO

136       supervisor(3), sys(3)
137
138
139
140Ericsson AB                     stdlib 3.14.2.1           supervisor_bridge(3)
Impressum