1supervisor_bridge(3) Erlang Module Definition supervisor_bridge(3)
2
6 supervisor_bridge - Generic supervisor bridge behavior.
7
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 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 The sys(3) module can be used for debugging a supervisor bridge.
22 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
28 start_link(Module, Args) -> Result
29 start_link(SupBridgeName, Module, Args) -> Result
31 Types:
33 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 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 * If SupBridgeName={local,Name}, the supervisor bridge is reg‐
51 istered locally as Name using register/2.
52 * If SupBridgeName={global,GlobalName}, the supervisor bridge
54 is registered globally as GlobalName using global:regis‐
55 ter_name/2.
56 * 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 If no name is provided, the supervisor bridge is not registered.
65 Module is the name of the callback module.
67 Args is an arbitrary term that is passed as the argument to Mod‐
69 ule:init/1.
70 * 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 * 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 * 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 * 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
89 The following functions must be exported from a supervisor_bridge call‐
90 back module.
91
93 Module:init(Args) -> Result
94 Types:
96 Args = term()
98 Result = {ok,Pid,State} | ignore | {error,Error}
99 Pid = pid()
100 State = term()
101 Error = term()
102 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 Args is the Args argument provided to the start function.
108 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 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 If the initialization fails, the function is to return {er‐
118 ror,Error}, where Error is any term, or ignore.
119 Module:terminate(Reason, State)
121 Types:
123 Reason = shutdown | term()
125 State = term()
126 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 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 State is taken from the return value of Module:init/1.
138
140 supervisor(3), sys(3)
141Ericsson AB stdlib 4.2 supervisor_bridge(3)