1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
7
<year>1997</year><year>2009</year>
8
<holder>Ericsson AB. All Rights Reserved.</holder>
11
The contents of this file are subject to the Erlang Public License,
12
Version 1.1, (the "License"); you may not use this file except in
13
compliance with the License. You should have received a copy of the
14
Erlang Public License along with this software. If not, it can be
15
retrieved online at http://www.erlang.org/.
17
Software distributed under the License is distributed on an "AS IS"
18
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
19
the License for the specific language governing rights and limitations
24
<title>Supervisor Behaviour</title>
29
<file>sup_princ.xml</file>
31
<p>This section should be read in conjunction with
32
<c>supervisor(3)</c>, where all details about the supervisor
33
behaviour is given.</p>
36
<title>Supervision Principles</title>
37
<p>A supervisor is responsible for starting, stopping and
38
monitoring its child processes. The basic idea of a supervisor is
39
that it should keep its child processes alive by restarting them
41
<p>Which child processes to start and monitor is specified by a
42
list of <seealso marker="#spec">child specifications</seealso>.
43
The child processes are started in the order specified by this
44
list, and terminated in the reversed order.</p>
48
<title>Example</title>
49
<p>The callback module for a supervisor starting the server from
50
the <seealso marker="gen_server_concepts#ex">gen_server chapter</seealso>
51
could look like this:</p>
52
<marker id="ex"></marker>
55
-behaviour(supervisor).
57
-export([start_link/0]).
61
supervisor:start_link(ch_sup, []).
64
{ok, {{one_for_one, 1, 60},
65
[{ch3, {ch3, start_link, []},
66
permanent, brutal_kill, worker, [ch3]}]}}.</code>
67
<p><c>one_for_one</c> is the <seealso marker="#strategy">restart strategy</seealso>.</p>
68
<p>1 and 60 defines the <seealso marker="#frequency">maximum restart frequency</seealso>.</p>
69
<p>The tuple <c>{ch3, ...}</c> is a <seealso marker="#spec">child specification</seealso>.</p>
73
<marker id="strategy"></marker>
74
<title>Restart Strategy</title>
77
<title>one_for_one</title>
78
<p>If a child process terminates, only that process is restarted.</p>
79
<marker id="sup4"></marker>
80
<image file="../design_principles/sup4.gif">
81
<icaption>One_For_One Supervision</icaption>
86
<title>one_for_all</title>
87
<p>If a child process terminates, all other child processes are
88
terminated and then all child processes, including
89
the terminated one, are restarted.</p>
90
<marker id="sup5"></marker>
91
<image file="../design_principles/sup5.gif">
92
<icaption>One_For_All Supervision</icaption>
97
<title>rest_for_one</title>
98
<p>If a child process terminates, the 'rest' of the child
99
processes -- i.e. the child processes after the terminated
100
process in start order -- are terminated. Then the terminated
101
child process and the rest of the child processes are restarted.</p>
106
<marker id="frequency"></marker>
107
<title>Maximum Restart Frequency</title>
108
<p>The supervisors have a built-in mechanism to limit the number of
109
restarts which can occur in a given time interval. This is
110
determined by the values of the two parameters <c>MaxR</c> and
111
<c>MaxT</c> in the start specification returned by the callback
112
function <c>init</c>:</p>
115
{ok, {{RestartStrategy, MaxR, MaxT},
116
[ChildSpec, ...]}}.</code>
117
<p>If more than <c>MaxR</c> number of restarts occur in the last
118
<c>MaxT</c> seconds, then the supervisor terminates all the child
119
processes and then itself.</p>
120
<p>When the supervisor terminates, then the next higher level
121
supervisor takes some action. It either restarts the terminated
122
supervisor, or terminates itself.</p>
123
<p>The intention of the restart mechanism is to prevent a situation
124
where a process repeatedly dies for the same reason, only to be
129
<marker id="spec"></marker>
130
<title>Child Specification</title>
131
<p>This is the type definition for a child specification:</p>
132
<code type="none"><![CDATA[
133
{Id, StartFunc, Restart, Shutdown, Type, Modules}
135
StartFunc = {M, F, A}
138
Restart = permanent | transient | temporary
139
Shutdown = brutal_kill | integer() >=0 | infinity
140
Type = worker | supervisor
141
Modules = [Module] | dynamic
142
Module = atom()]]></code>
143
<list type="bulleted">
145
<p><c>Id</c> is a name that is used to identify the child
146
specification internally by the supervisor.</p>
149
<p><c>StartFunc</c> defines the function call used to start
150
the child process. It is a module-function-arguments tuple
151
used as <c>apply(M, F, A)</c>.</p>
152
<p>It should be (or result in) a call to
153
<c>supervisor:start_link</c>, <c>gen_server:start_link</c>,
154
<c>gen_fsm:start_link</c> or <c>gen_event:start_link</c>.
155
(Or a function compliant with these functions, see
156
<c>supervisor(3)</c> for details.</p>
159
<p><c>Restart</c> defines when a terminated child process should
161
<list type="bulleted">
162
<item>A <c>permanent</c> child process is always restarted.</item>
163
<item>A <c>temporary</c> child process is never restarted.</item>
164
<item>A <c>transient</c> child process is restarted only if it
165
terminates abnormally, i.e. with another exit reason than
166
<c>normal</c>.</item>
170
<marker id="shutdown"></marker>
171
<p><c>Shutdown</c> defines how a child process should be
173
<list type="bulleted">
174
<item><c>brutal_kill</c> means the child process is
175
unconditionally terminated using <c>exit(Child, kill)</c>.</item>
176
<item>An integer timeout value means that the supervisor tells
177
the child process to terminate by calling
178
<c>exit(Child, shutdown)</c> and then waits for an exit
179
signal back. If no exit signal is received within
180
the specified time, the child process is unconditionally
181
terminated using <c>exit(Child, kill)</c>.</item>
182
<item>If the child process is another supervisor, it should be
183
set to <c>infinity</c> to give the subtree enough time to
188
<p><c>Type</c> specifies if the child process is a supervisor or
192
<p><c>Modules</c> should be a list with one element
193
<c>[Module]</c>, where <c>Module</c> is the name of
194
the callback module, if the child process is a supervisor,
195
gen_server or gen_fsm. If the child process is a gen_event,
196
<c>Modules</c> should be <c>dynamic</c>.</p>
197
<p>This information is used by the release handler during
198
upgrades and downgrades, see
199
<seealso marker="release_handling">Release Handling</seealso>.</p>
202
<p>Example: The child specification to start the server <c>ch3</c>
203
in the example above looks like:</p>
206
{ch3, start_link, []},
207
permanent, brutal_kill, worker, [ch3]}</code>
208
<p>Example: A child specification to start the event manager from
210
<seealso marker="events#mgr">gen_event</seealso>:</p>
213
{gen_event, start_link, [{local, error_man}]},
214
permanent, 5000, worker, dynamic}</code>
215
<p>Both the server and event manager are registered processes which
216
can be expected to be accessible at all times, thus they are
217
specified to be <c>permanent</c>.</p>
218
<p><c>ch3</c> does not need to do any cleaning up before
219
termination, thus no shutdown time is needed but
220
<c>brutal_kill</c> should be sufficient. <c>error_man</c> may
221
need some time for the event handlers to clean up, thus
222
<c>Shutdown</c> is set to 5000 ms.</p>
223
<p>Example: A child specification to start another supervisor:</p>
226
{sup, start_link, []},
227
transient, infinity, supervisor, [sup]}</code>
231
<marker id="super_tree"></marker>
232
<title>Starting a Supervisor</title>
233
<p>In the example above, the supervisor is started by calling
234
<c>ch_sup:start_link()</c>:</p>
237
supervisor:start_link(ch_sup, []).</code>
238
<p><c>ch_sup:start_link</c> calls the function
239
<c>supervisor:start_link/2</c>. This function spawns and links to
240
a new process, a supervisor.</p>
241
<list type="bulleted">
242
<item>The first argument, <c>ch_sup</c>, is the name of
243
the callback module, that is the module where the <c>init</c>
244
callback function is located.</item>
245
<item>The second argument, [], is a term which is passed as-is to
246
the callback function <c>init</c>. Here, <c>init</c> does not
247
need any indata and ignores the argument.</item>
249
<p>In this case, the supervisor is not registered. Instead its pid
250
must be used. A name can be specified by calling
251
<c>supervisor:start_link({local, Name}, Module, Args)</c> or
252
<c>supervisor:start_link({global, Name}, Module, Args)</c>.</p>
253
<p>The new supervisor process calls the callback function
254
<c>ch_sup:init([])</c>. <c>init</c> is expected to return
255
<c>{ok, StartSpec}</c>:</p>
258
{ok, {{one_for_one, 1, 60},
259
[{ch3, {ch3, start_link, []},
260
permanent, brutal_kill, worker, [ch3]}]}}.</code>
261
<p>The supervisor then starts all its child processes according to
262
the child specifications in the start specification. In this case
263
there is one child process, <c>ch3</c>.</p>
264
<p>Note that <c>supervisor:start_link</c> is synchronous. It does
265
not return until all child processes have been started.</p>
269
<title>Adding a Child Process</title>
270
<p>In addition to the static supervision tree, we can also add
271
dynamic child processes to an existing supervisor with
272
the following call:</p>
274
supervisor:start_child(Sup, ChildSpec)</code>
275
<p><c>Sup</c> is the pid, or name, of the supervisor.
276
<c>ChildSpec</c> is a <seealso marker="#spec">child specification</seealso>.</p>
277
<p>Child processes added using <c>start_child/2</c> behave in
278
the same manner as the other child processes, with the following
279
important exception: If a supervisor dies and is re-created, then
280
all child processes which were dynamically added to the supervisor
285
<title>Stopping a Child Process</title>
286
<p>Any child process, static or dynamic, can be stopped in
287
accordance with the shutdown specification:</p>
289
supervisor:terminate_child(Sup, Id)</code>
290
<p>The child specification for a stopped child process is deleted
291
with the following call:</p>
293
supervisor:delete_child(Sup, Id)</code>
294
<p><c>Sup</c> is the pid, or name, of the supervisor.
295
<c>Id</c> is the id specified in the <seealso marker="#spec">child specification</seealso>.</p>
296
<p>As with dynamically added child processes, the effects of
297
deleting a static child process is lost if the supervisor itself
302
<title>Simple-One-For-One Supervisors</title>
303
<p>A supervisor with restart strategy <c>simple_one_for_one</c> is
304
a simplified one_for_one supervisor, where all child processes are
305
dynamically added instances of the same process.</p>
306
<p>Example of a callback module for a simple_one_for_one supervisor:</p>
309
-behaviour(supervisor).
311
-export([start_link/0]).
315
supervisor:start_link(simple_sup, []).
318
{ok, {{simple_one_for_one, 0, 1},
319
[{call, {call, start_link, []},
320
temporary, brutal_kill, worker, [call]}]}}.</code>
321
<p>When started, the supervisor will not start any child processes.
322
Instead, all child processes are added dynamically by calling:</p>
324
supervisor:start_child(Sup, List)</code>
325
<p><c>Sup</c> is the pid, or name, of the supervisor.
326
<c>List</c> is an arbitrary list of terms which will be added to
327
the list of arguments specified in the child specification. If
328
the start function is specified as <c>{M, F, A}</c>, then
329
the child process is started by calling
330
<c>apply(M, F, A++List)</c>.</p>
331
<p>For example, adding a child to <c>simple_sup</c> above:</p>
333
supervisor:start_child(Pid, [id1])</code>
334
<p>results in the child process being started by calling
335
<c>apply(call, start_link, []++[id1])</c>, or actually:</p>
337
call:start_link(id1)</code>
341
<title>Stopping</title>
342
<p>Since the supervisor is part of a supervision tree, it will
343
automatically be terminated by its supervisor. When asked to
344
shutdown, it will terminate all child processes in reversed start
345
order according to the respective shutdown specifications, and
346
then terminate itself.</p>
added
removed
system/doc/design_principles/sup_princ.xml
