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 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408
|
<HTML>
<HEAD>
<!-- refpage -->
<TITLE>supervisor</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<CENTER>
<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Erlang Systems]" SRC="min_head.gif"></A>
<H1>supervisor</H1>
</CENTER>
<H3>MODULE</H3>
<UL>
supervisor</UL>
<H3>MODULE SUMMARY</H3>
<UL>
Generic Supervisor Behaviour.</UL>
<H3>DESCRIPTION</H3>
<UL>
<P>A behaviour module for implementing a supervisor, a process which
supervises other processes called child processes. A child process can
either be another supervisor or a worker process. Worker processes are
normally implemented using one of the <CODE>gen_event</CODE>, <CODE>gen_fsm</CODE>,
or <CODE>gen_server</CODE> behaviours. A supervisor implemented using this
module will have a standard set of interface functions and include
functionality for tracing and error reporting. Supervisors are used to
build an hierarchical process structure called a supervision tree, a
nice way to structure a fault tolerant application. Refer to
<STRONG>OTP Design Principles</STRONG> for more information.<P>A supervisor assumes the definition of which child processes to
supervise to be located in a callback module exporting a pre-defined
set of functions.<P>Unless otherwise stated, all functions in this module will fail if
the specified supervisor does not exist or if bad arguments are given.
</UL>
<H3>Supervision Principles</H3>
<UL>
<P>The supervisor is responsible for starting, stopping and monitoring
its child processes. The basic idea of a supervisor is that it should
keep its child processes alive by restarting them when necessary.<P>The children of a supervisor is defined as a list of <STRONG>child
specifications</STRONG>. When the supervisor is started, the child
processes are started in order from left to right according to this
list. When the supervisor terminates, it first terminates its child
processes in reversed start order, from right to left.<P>
<P>A supervisor can have one of the following <STRONG>restart
strategies</STRONG>:<P><UL>
<LI><CODE>one_for_one</CODE> - if one child process terminates and should
be restarted, only that child process is affected.</LI><BR>
<LI><CODE>one_for_all</CODE> - if one child process terminates and should
be restarted, all other child processes are terminated and then all
child processes are restarted.</LI><BR>
<LI><CODE>rest_for_one</CODE> - if one child process terminates and should
be restarted, the 'rest' of the child processes -- i.e. the child
processes after the terminated child process in the start order --
are terminated. Then the terminated child process and all child
processes after it are restarted.</LI><BR>
<LI> <CODE>simple_one_for_one</CODE> - a simplified <CODE>one_for_one</CODE>
supervisor, where all child processes are dynamically added
instances of the same process type, i.e. running the same code.<BR>
The functions <CODE>terminate_child/2</CODE>, <CODE>delete_child/2</CODE> and
<CODE>restart_child/2</CODE> are invalid for <CODE>simple_one_for_one</CODE>
supervisors and will return <CODE>{error,simple_one_for_one}</CODE> if
the specified supervisor uses this restart strategy.<BR>
</LI><BR>
</UL>
<P>To prevent a supervisor from getting into an infinite loop of child
process terminations and restarts, a <STRONG>maximum restart frequency</STRONG>
is defined using two integer values <CODE>MaxR</CODE> and <CODE>MaxT</CODE>. If
more than <CODE>MaxR</CODE> restarts occur within <CODE>MaxT</CODE> seconds,
the supervisor terminates all child processes and then itself.<P>This is the type definition of a child specification:<PRE>child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules}
Id = term()
StartFunc = {M,F,A}
M = F = atom()
A = [term()]
Restart = permanent | transient | temporary
Shutdown = brutal_kill | int()>=0 | infinity
Type = worker | supervisor
Modules = [Module] | dynamic
Module = atom()
</PRE>
<P><UL>
<LI> <CODE>Id</CODE> is a name that is used to identify the child
specification internally by the supervisor.<BR>
</LI><BR>
<LI> <CODE>StartFunc</CODE> defines the function call used to start
the child process. It should be a module-function-arguments tuple
<CODE>{M,F,A}</CODE> used as <CODE>apply(M,F,A)</CODE>.<BR>
<BR>
The start function <STRONG>must create and link to</STRONG> the child
process, and should return <CODE>{ok,Child}</CODE> or
<CODE>{ok,Child,Info}</CODE> where <CODE>Child</CODE> is the pid of the child
process and <CODE>Info</CODE> an arbitrary term which is ignored by
the supervisor.<BR>
<BR>
The start function can also return <CODE>ignore</CODE> if the child
process for some reason cannot be started, in which case the child
specification will be kept by the supervisor but the non-existing
child process will be ignored.<BR>
<BR>
If something goes wrong, the function may also return an error
tuple <CODE>{error,Error}</CODE>.<BR>
<BR>
Note that the <CODE>start_link</CODE> functions of the different
behaviour modules fulfill the above requirements.<BR>
</LI><BR>
<LI> <CODE>Restart</CODE> defines when a terminated child process should be
restarted. A <CODE>permanent</CODE> child process should always be
restarted, a <CODE>temporary</CODE> child process should never be
restarted and a <CODE>transient</CODE> child process should be restarted
only if it terminates abnormally, i.e. with another exit reason
than <CODE>normal</CODE>.<BR>
</LI><BR>
<LI> <CODE>Shutdown</CODE> defines how a child process should be terminated.
<CODE>brutal_kill</CODE> means the child process will be unconditionally
terminated using <CODE>exit(Child,kill)</CODE>. An integer timeout value
means that the supervisor will tell the child process to terminate
by calling <CODE>exit(Child,shutdown)</CODE> and then wait for an exit
signal from the child process. If no exit signal is received within
the specified time, the child process is unconditionally terminated
using <CODE>exit(Child,kill)</CODE>.<BR>
If the child process is another supervisor, <CODE>Shutdown</CODE> should
be set to <CODE>infinity</CODE> to give the subtree ample time to
shutdown.<BR>
</LI><BR>
<LI> <CODE>Type</CODE> specifies if the child process is a supervisor or
a worker.<BR>
</LI><BR>
<LI> <CODE>Modules</CODE> is used by the release handler during code
replacement to determine which processes are using a certain
module. As a rule of thumb <CODE>Modules</CODE> should be a list with one
element <CODE>[Module]</CODE>, where <CODE>Module</CODE> is the name of
the callback module, if the child process is a supervisor,
gen_server or gen_fsm. If the child process is an event manager
(gen_event) with a dynamic set of callback modules, <CODE>Modules</CODE>
should be <CODE>dynamic</CODE>. See <STRONG>SASL User's Guide</STRONG> for more
information.<BR>
</LI><BR>
<LI> Internally, the supervisor also keeps track of the pid
<CODE>Child</CODE> of the child process, or <CODE>undefined</CODE> if no pid
exists.<BR>
</LI><BR>
</UL>
</UL>
<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(SupName, Module, Args) -> Result</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>SupName = {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}} | shutdown | term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Creates a supervisor process, linked to the calling process,
which calls <CODE>Module:init/1</CODE> to find out about restart
strategy, maximum restart frequency and child processes. To ensure
a synchronized start-up procedure, this function does not return
until <CODE>Module:init/1</CODE> has returned and all child processes
have been started.
<P>If <CODE>SupName={local,Name}</CODE> the supervisor is registered
locally as <CODE>Name</CODE> using <CODE>register/2</CODE>.
If <CODE>SupName={global,Name}</CODE> the supervisor is registered
globally as <CODE>Name</CODE> using <CODE>global:register_name/2</CODE>.
If no name is provided, the supervisor is not registered.
If there already exists a process with the specified
<CODE>SupName</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 and its child processes are successfully
created (i.e. if all child process start functions return
<CODE>{ok,Child}</CODE>, <CODE>{ok,Child,Info}</CODE>, or <CODE>ignore</CODE>)
the function returns <CODE>{ok,Pid}</CODE>, where <CODE>Pid</CODE> is
the pid of the supervisor.<P>If <CODE>Module:init/1</CODE> returns <CODE>ignore</CODE>, this function
returns <CODE>ignore</CODE> as well and the supervisor terminates with
reason <CODE>normal</CODE>.
If <CODE>Module:init/1</CODE> fails or returns 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
terminates with reason <CODE>Term</CODE>.
<P>If any child process start function fails or returns an error
tuple or an erroneous value, the function returns
<CODE>{error,shutdown}</CODE> and the supervisor terminates all started
child processes and then itself with reason <CODE>shutdown</CODE>.</UL>
<P><A NAME="start_child%2"><STRONG><CODE>start_child(SupRef, ChildSpec) -> Result</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>SupRef = Name | {Name,Node} | {global,Name} | pid()</CODE></STRONG><BR>
<STRONG><CODE> Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>ChildSpec = child_spec() | [term()]</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,Child} | {ok,Child,Info} | {error,Error}</CODE></STRONG><BR>
<STRONG><CODE> Child = pid() | undefined</CODE></STRONG><BR>
<STRONG><CODE> Info = term()</CODE></STRONG><BR>
<STRONG><CODE> Error = already_present | {already_started,Child} | term()
</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Dynamically adds a child specification to the supervisor
<CODE>SupRef</CODE> which starts the corresponding child process.<P><CODE>SupRef</CODE> can be:<P><UL>
<LI>the pid,</LI><BR>
<LI><CODE>Name</CODE>, if the supervisor is locally registered,</LI><BR>
<LI><CODE>{Name,Node}</CODE>, if the supervisor is locally registered
at another node, or</LI><BR>
<LI><CODE>{global,Name}</CODE>, if the supervisor is globally
registered.</LI><BR>
</UL>
<P><CODE>ChildSpec</CODE> should be a valid child specification (unless
the supervisor is a <CODE>simple_one_for_one</CODE> supervisor, see
below). The child process will be started by using the start
function as defined in the child specification.<P>If the case of a <CODE>simple_one_for_one</CODE> supervisor, the child
specification defined in <CODE>Module:init/1</CODE> will be used and
<CODE>ChildSpec</CODE> should instead be an arbitrary list of terms
<CODE>List</CODE>. The child process will then be started by appending
<CODE>List</CODE> to the existing start function arguments, i.e. by
calling <CODE>apply(M, F, A++List)</CODE> where <CODE>{M,F,A}</CODE> is
the start function defined in the child specification.<P>If there already exists a child specification with the specified
<CODE>Id</CODE>, <CODE>ChildSpec</CODE> is discarded and the function returns
<CODE>{error,already_present}</CODE> or
<CODE>{error,{already_started,Child}}</CODE>, depending on if
the corresponding child process is running or not.<P>If the child process start function returns <CODE>{ok,Child}</CODE> or
<CODE>{ok,Child,Info}</CODE>, the child specification and pid is added
to the supervisor and the function returns the same value.<P>If the child process start function returns <CODE>ignore</CODE>,
the child specification is added to the supervisor, the pid is set
to <CODE>undefined</CODE> and the function returns <CODE>{ok,undefined}</CODE>.
<P>If the child process start function returns an error tuple or
an erroneous value, or if it fails, the child specification is
discarded and the function returns <CODE>{error,Error}</CODE> where
<CODE>Error</CODE> is a term containing information about the error
and child specification.</UL>
<P><A NAME="terminate_child%2"><STRONG><CODE>terminate_child(SupRef, Id) -> Result</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>SupRef = Name | {Name,Node} | {global,Name} | pid()</CODE></STRONG><BR>
<STRONG><CODE> Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Id = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = ok | {error,Error}</CODE></STRONG><BR>
<STRONG><CODE> Error = not_found | simple_one_for_one</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Tells the supervisor <CODE>SupRef</CODE> to terminate the child process
corresponding to the child specification identified by <CODE>Id</CODE>.
The process, if there is one, is terminated but the child
specification is kept by the supervisor. This means that the child
process may be later be restarted by the supervisor.
The child process can also be restarted explicitly by calling
<CODE>restart_child/2</CODE>. Use <CODE>delete_child/2</CODE> to remove
the child specification.<P>See <CODE>start_child/2</CODE> for a description of <CODE>SupRef</CODE>.<P>If successful, the function returns <CODE>ok</CODE>.
If there is no child specification with the specified
<CODE>Id</CODE>, the function returns <CODE>{error,not_found}</CODE>.</UL>
<P><A NAME="delete_child%2"><STRONG><CODE>delete_child(SupRef, Id) -> Result</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>SupRef = Name | {Name,Node} | {global,Name} | pid()</CODE></STRONG><BR>
<STRONG><CODE> Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Id = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = ok | {error,Error}</CODE></STRONG><BR>
<STRONG><CODE> Error = running | not_found | simple_one_for_one</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Tells the supervisor <CODE>SupRef</CODE> to delete the child
specification identified by <CODE>Id</CODE>. The corresponding child
process must not be running, use <CODE>terminate_child/2</CODE> to
terminate it.<P>See <CODE>start_child/2</CODE> for a description of <CODE>SupRef</CODE>.<P>If successful, the function returns <CODE>ok</CODE>.
If the child specification identified by <CODE>Id</CODE> exists but
the corresponding child process is running, the function returns
<CODE>{error,running}</CODE>.
If the child specification identified by <CODE>Id</CODE> does not exist,
the function returns <CODE>{error,not_found}</CODE>.</UL>
<P><A NAME="restart_child%2"><STRONG><CODE>restart_child(SupRef, Id) -> Result</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>SupRef = Name | {Name,Node} | {global,Name} | pid()</CODE></STRONG><BR>
<STRONG><CODE> Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Id = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,Child} | {ok,Child,Info} | {error,Error}</CODE></STRONG><BR>
<STRONG><CODE> Child = pid() | undefined</CODE></STRONG><BR>
<STRONG><CODE> Error = running | not_found | simple_one_for_one | term()
</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Tells the supervisor <CODE>SupRef</CODE> to restart a child process
corresponding to the child specification identified by <CODE>Id</CODE>.
The child specification must exist and the corresponding child
process must not be running.<P>See <CODE>start_child/2</CODE> for a description of <CODE>SupRef</CODE>.<P>If the child specification identified by <CODE>Id</CODE> does not exist,
the function returns <CODE>{error,not_found}</CODE>.
If the child specification exists but the corresponding process
is already running, the function returns <CODE>{error,running}</CODE>.
<P>If the child process start function returns <CODE>{ok,Child}</CODE> or
<CODE>{ok,Child,Info}</CODE>, the pid is added to the supervisor and
the function returns the same value.<P>If the child process start function returns <CODE>ignore</CODE>,
the pid remains set to <CODE>undefined</CODE> and the function returns
<CODE>{ok,undefined}</CODE>.<P>If the child process start function returns an error tuple or
an erroneous value, or if it fails, the function returns
<CODE>{error,Error}</CODE> where <CODE>Error</CODE> is a term containing
information about the error.</UL>
<P><A NAME="which_children%1"><STRONG><CODE>which_children(SupRef) -> [{Id,Child,Type,Modules}]</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>SupRef = Name | {Name,Node} | {global,Name} | pid()</CODE></STRONG><BR>
<STRONG><CODE> Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Id = term() | undefined</CODE></STRONG><BR>
<STRONG><CODE>Child = pid() | undefined</CODE></STRONG><BR>
<STRONG><CODE>Type = worker | supervisor</CODE></STRONG><BR>
<STRONG><CODE>Modules = [Module] | dynamic</CODE></STRONG><BR>
<STRONG><CODE> Module = atom()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Returns a list with information about all child specifications and
child processes belonging to the supervisor <CODE>SupRef</CODE>.<P>See <CODE>start_child/2</CODE> for a description of <CODE>SupRef</CODE>.<P>The information given for each child specification/process is:
<P><UL>
<LI><CODE>Id</CODE> - as defined in the child specification or
<CODE>undefined</CODE> in the case of a <CODE>simple_one_for_one</CODE>
supervisor.</LI><BR>
<LI><CODE>Child</CODE> - the pid of the corresponding child process, or
<CODE>undefined</CODE> if there is no such process.</LI><BR>
<LI><CODE>Type</CODE> - as defined in the child specification.</LI><BR>
<LI><CODE>Modules</CODE> - as defined in the child specification.
</LI><BR>
</UL>
</UL>
<P><A NAME="check_childspecs%1"><STRONG><CODE>check_childspecs([ChildSpec]) -> Result</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>ChildSpec = child_spec()</CODE></STRONG><BR>
<STRONG><CODE>Result = ok | {error,Error}</CODE></STRONG><BR>
<STRONG><CODE> Error = term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function takes a list of child specification as argument
and returns <CODE>ok</CODE> if all of them are syntactically correct,
or <CODE>{error,Error}</CODE> otherwise.</UL>
<H3>CALLBACK FUNCTIONS</H3>
<UL>
<P>The following functions should be exported from a <CODE>supervisor</CODE>
callback module.</UL>
<H3>EXPORTS</H3>
<P><A NAME="Module:init%1"><STRONG><CODE>Module:init(Args) -> Result</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Args = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,{{RestartStrategy,MaxR,MaxT},[ChildSpec]}} | ignore
</CODE></STRONG><BR>
<STRONG><CODE> RestartStrategy = one_for_all | one_for_one | rest_for_one
| simple_one_for_one</CODE></STRONG><BR>
<STRONG><CODE> MaxR = MaxT = int()>=0</CODE></STRONG><BR>
<STRONG><CODE> ChildSpec = child_spec()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Whenever a supervisor is started using
<CODE>supervisor:start_link/2,3</CODE>, this function is called by
the new process to find out about restart strategy, maximum
restart frequency and child specifications.<P><CODE>Args</CODE> is the <CODE>Args</CODE> argument provided to the start
function.<P><CODE>RestartStrategy</CODE> is the restart strategy and <CODE>MaxR</CODE> and
<CODE>MaxT</CODE> defines the maximum restart frequency of
the supervisor. <CODE>[ChildSpec]</CODE> is a list of valid child
specifications defining which child processes the supervisor
should start and monitor. See the discussion about Supervision
Principles above.<P>Note that when the restart strategy is <CODE>simple_one_for_one</CODE>,
the list of child specifications must be a list with one child
specification only. (The <CODE>Id</CODE> is ignored). No child process
is then started during the initialization phase, but all children
are assumed to be started dynamically using
<CODE>supervisor:start_child/2</CODE>.<P>The function may also return <CODE>ignore</CODE>.</UL>
<H3>SEE ALSO</H3>
<UL>
<P>gen_event(3), gen_fsm(3), gen_server(3), sys(3)</UL>
<H3>AUTHORS</H3>
<UL>
Gunilla Hugosson - support@erlang.ericsson.se<BR>
</UL>
<CENTER>
<HR>
<FONT SIZE=-1>stdlib 1.10<BR>
Copyright © 1991-2001
<A HREF="http://www.erlang.se">Ericsson Utvecklings AB</A><BR>
<!--#include virtual="/ssi/otp_footer.html"-->
</FONT>
</CENTER>
</BODY>
</HTML>
|