1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
<TITLE>supervisor_bridge</TITLE>
<SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
<STYLE TYPE="text/css">
<!--
.REFBODY { margin-left: 13mm }
.REFTYPES { margin-left: 8mm }
-->
</STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
<IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>supervisor_bridge</H1>
</CENTER>
<H3>MODULE</H3>
<DIV CLASS=REFBODY>
supervisor_bridge
</DIV>
<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
Generic Supervisor Bridge Behaviour.
</DIV>
<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>
<P>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 <STRONG>OTP Design Principles</STRONG>
for more information.
<P>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.
<P>The <CODE>sys</CODE> module can be used for debugging a
supervisor_bridge.
<P>Unless otherwise stated, all functions in this module will fail if
the specified supervisor_bridge does not exist or if bad arguments are
given.
</DIV>
<H3>EXPORTS</H3>
<P><A NAME="start_link/2"><STRONG><CODE>start_link(Module, Args) -> Result</CODE></STRONG></A><BR>
<A NAME="start_link/3"><STRONG><CODE>start_link(SupBridgeName, Module, Args) -> Result</CODE></STRONG></A><BR>
<DIV CLASS=REFBODY><P>Types:
<DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>SupBridgeName = {local,Name} | {global,Name}</CODE></STRONG><BR>
<STRONG><CODE>Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Args = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,Pid} | ignore | {error,Error}</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid()</CODE></STRONG><BR>
<STRONG><CODE>Error = {already_started,Pid} | term()</CODE></STRONG><BR>
</DIV>
</DIV>
<DIV CLASS=REFBODY>
<P>Creates a supervisor_bridge process, linked to the calling
process, which calls <CODE>Module:init/1</CODE> to start the subsystem.
To ensure a synchronized start-up procedure, this function does
not return until <CODE>Module:init/1</CODE> has returned.
<P>If <CODE>SupBridgeName={local,Name}</CODE> the supervisor_bridge is
registered locally as <CODE>Name</CODE> using <CODE>register/2</CODE>.
If <CODE>SupBridgeName={global,Name}</CODE> the supervisor_bridge is
registered globally as <CODE>Name</CODE> using
<CODE>global:register_name/2</CODE>.
If no name is provided, the supervisor_bridge is not registered.
If there already exists a process with the specified
<CODE>SupBridgeName</CODE> the function returns
<CODE>{error,{already_started,Pid}}</CODE>, where <CODE>Pid</CODE> is the pid
of that process.
<P><CODE>Module</CODE> is the name of the callback module.
<P><CODE>Args</CODE> is an arbitrary term which is passed as the argument
to <CODE>Module:init/1</CODE>.
<P>If the supervisor_bridge and the subsystem are successfully
started the function returns <CODE>{ok,Pid}</CODE>, where <CODE>Pid</CODE> is
is the pid of the supervisor_bridge.
<P>If <CODE>Module:init/1</CODE> returns <CODE>ignore</CODE>, this function
returns <CODE>ignore</CODE> as well and the supervisor_bridge terminates
with reason <CODE>normal</CODE>.
If <CODE>Module:init/1</CODE> fails or returns an error tuple or an
incorrect value, this function returns <CODE>{error,Term}</CODE> where
<CODE>Term</CODE> is a term with information about the error, and
the supervisor_bridge terminates with reason <CODE>Term</CODE>.
</DIV>
<H3>CALLBACK FUNCTIONS</H3>
<DIV CLASS=REFBODY>
<P>The following functions should be exported from a
<CODE>supervisor_bridge</CODE> callback module.
</DIV>
<H3>EXPORTS</H3>
<P><A NAME="Module:init/1"><STRONG><CODE>Module:init(Args) -> Result</CODE></STRONG></A><BR>
<DIV CLASS=REFBODY><P>Types:
<DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Args = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,Pid,State} | ignore | {error,Error}</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid()</CODE></STRONG><BR>
<STRONG><CODE>State = term()</CODE></STRONG><BR>
<STRONG><CODE>Error = term()</CODE></STRONG><BR>
</DIV>
</DIV>
<DIV CLASS=REFBODY>
<P>Whenever a supervisor_bridge is started using
<CODE>supervisor_bridge:start_link/2,3</CODE>, this function is called
by the new process to start the subsystem and initialize.
<P><CODE>Args</CODE> is the <CODE>Args</CODE> argument provided to the start
function.
<P>The function should return <CODE>{ok,Pid,State}</CODE> where <CODE>Pid</CODE>
is the pid of the main process in the subsystem and <CODE>State</CODE>
is any term.
<P>If later <CODE>Pid</CODE> terminates with a reason <CODE>Reason</CODE>,
the supervisor bridge will terminate with reason <CODE>Reason</CODE> as
well.
If later the supervisor_bridge is stopped by its supervisor with
reason <CODE>Reason</CODE>, it will call
<CODE>Module:terminate(Reason,State)</CODE> to terminate.
<P>If something goes wrong during the initialization the function
should return <CODE>{error,Error}</CODE> where <CODE>Error</CODE> is any
term, or <CODE>ignore</CODE>.
</DIV>
<P><A NAME="Module:terminate/2"><STRONG><CODE>Module:terminate(Reason, State)</CODE></STRONG></A><BR>
<DIV CLASS=REFBODY><P>Types:
<DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Reason = shutdown | term()</CODE></STRONG><BR>
<STRONG><CODE>State = term()</CODE></STRONG><BR>
</DIV>
</DIV>
<DIV CLASS=REFBODY>
<P>This function is called by the supervisor_bridge when it is about
to terminate. It should be the opposite of <CODE>Module:init/1</CODE>
and stop the subsystem and do any necessary cleaning up.
The return value is ignored.
<P><CODE>Reason</CODE> is <CODE>shutdown</CODE> 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 <CODE>Term</CODE>,
<CODE>Reason</CODE> will be <CODE>Term</CODE>.
<P><CODE>State</CODE> is taken from the return value of
<CODE>Module:init/1</CODE>.
</DIV>
<H3>SEE ALSO</H3>
<DIV CLASS=REFBODY>
<P><A HREF="supervisor.html">supervisor(3)</A>,
<A HREF="sys.html">sys(3)</A>
</DIV>
<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Martin Bjrklund - support@erlang.ericsson.se<BR>
Gunilla Hugosson - support@erlang.ericsson.se<BR>
</DIV>
<CENTER>
<HR>
<SMALL>stdlib 1.14.2<BR>
Copyright © 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>
|
