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
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>1997</year><year>2022</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</legalnotice>
<title>Supervisor Behaviour</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
<file>sup_princ.xml</file>
</header>
<p>This section should be read with the
<seeerl marker="stdlib:supervisor">supervisor(3)</seeerl> manual page
in STDLIB, where all details about the supervisor
behaviour is given.</p>
<section>
<title>Supervision Principles</title>
<p>A supervisor is responsible for starting, stopping, and
monitoring its child processes. The basic idea of a supervisor is
that it is to keep its child processes alive by restarting them
when necessary.</p>
<p>Which child processes to start and monitor is specified by a
list of <seeguide marker="#spec">child specifications</seeguide>.
The child processes are started in the order specified by this
list, and terminated in the reversed order.</p>
</section>
<section>
<title>Example</title>
<p>The callback module for a supervisor starting the server from
<seeguide marker="gen_server_concepts#ex">gen_server Behaviour</seeguide>
can look as follows:</p>
<marker id="ex"></marker>
<code type="none">
-module(ch_sup).
-behaviour(supervisor).
-export([start_link/0]).
-export([init/1]).
start_link() ->
supervisor:start_link(ch_sup, []).
init(_Args) ->
SupFlags = #{strategy => one_for_one, intensity => 1, period => 5},
ChildSpecs = [#{id => ch3,
start => {ch3, start_link, []},
restart => permanent,
shutdown => brutal_kill,
type => worker,
modules => [ch3]}],
{ok, {SupFlags, ChildSpecs}}.</code>
<p>The <c>SupFlags</c> variable in the return value
from <c>init/1</c> represents
the <seeguide marker="#flags">supervisor flags</seeguide>.</p>
<p>The <c>ChildSpecs</c> variable in the return value
from <c>init/1</c> is a list of <seeguide marker="#spec">child
specifications</seeguide>.</p>
</section>
<section>
<marker id="flags"/>
<title>Supervisor Flags</title>
<p>This is the type definition for the supervisor flags:</p>
<code type="none"><![CDATA[
sup_flags() = #{strategy => strategy(), % optional
intensity => non_neg_integer(), % optional
period => pos_integer(), % optional
auto_shutdown => auto_shutdown()} % optional
strategy() = one_for_all
| one_for_one
| rest_for_one
| simple_one_for_one
auto_shutdown() = never
| any_significant
| all_significant]]></code>
<list type="bulleted">
<item>
<p><c>strategy</c> specifies
the <seeguide marker="#strategy">restart
strategy</seeguide>.</p>
</item>
<item>
<p><c>intensity</c> and <c>period</c> specify
the <seeguide marker="#max_intensity">maximum restart
intensity</seeguide>.</p>
</item>
<item>
<p><c>auto_shutdown</c> specifies if and when a supervisor should
<seeguide marker="#automatic-shutdown">automatically shut itself
down</seeguide>.</p>
</item>
</list>
</section>
<section>
<marker id="strategy"/>
<title>Restart Strategy</title>
<p> The restart strategy is specified by
the <c>strategy</c> key in the supervisor flags map returned by
the callback function <c>init</c>:</p>
<code type="none">
SupFlags = #{strategy => Strategy, ...}</code>
<p>The <c>strategy</c> key is optional in this map. If it is not
given, it defaults to <c>one_for_one</c>.</p>
<note>
<p>For simplicity, the diagrams shown in this section display a
setup where all the depicted children are assumed to have
a <seeguide marker="#restart">restart type</seeguide> of
<c>permanent</c>.</p>
</note>
<section>
<title>one_for_one</title>
<p>If a child process terminates, only that process is restarted.</p>
<marker id="sup4"></marker>
<image file="../design_principles/sup-one_for_one.svg" width="80%">
<icaption>One_For_One Supervision</icaption>
</image>
</section>
<section>
<title>one_for_all</title>
<p>If a child process terminates, all other child processes are
terminated, and then all child processes, including
the terminated one, are restarted.</p>
<marker id="sup5"></marker>
<image file="../design_principles/sup-one_for_all.svg" width="80%">
<icaption>One_For_All Supervision</icaption>
</image>
</section>
<section>
<title>rest_for_one</title>
<p>If a child process terminates, the rest of the child
processes (that is, the child processes after the terminated
process in start order) are terminated. Then the terminated
child process and the rest of the child processes are restarted.</p>
<marker id="sup6"></marker>
<image file="../design_principles/sup-rest_for_one.svg" width="80%">
<icaption>Rest_For_One Supervision</icaption>
</image>
</section>
<section>
<title>simple_one_for_one</title>
<p>See <seeguide marker="#simple">simple-one-for-one
supervisors</seeguide>.</p>
</section>
</section>
<section>
<marker id="max_intensity"></marker>
<title>Maximum Restart Intensity</title>
<p>The supervisors have a built-in mechanism to limit the number of
restarts which can occur in a given time interval. This is
specified by the two keys <c>intensity</c> and
<c>period</c> in the supervisor flags map returned by the
callback function <c>init</c>:</p>
<code type="none">
SupFlags = #{intensity => MaxR, period => MaxT, ...}</code>
<p>If more than <c>MaxR</c> number of restarts occur in the last
<c>MaxT</c> seconds, the supervisor terminates all the child
processes and then itself.
The termination reason for the supervisor itself in that case will be
<c>shutdown</c>.</p>
<p>When the supervisor terminates, then the next higher-level
supervisor takes some action. It either restarts the terminated
supervisor or terminates itself.</p>
<p>The intention of the restart mechanism is to prevent a situation
where a process repeatedly dies for the same reason, only to be
restarted again.</p>
<p>The keys <c>intensity</c> and <c>period</c> are optional in the
supervisor flags map. If they are not given, they default
to <c>1</c> and <c>5</c>, respectively.</p>
<section>
<title>Tuning the intensity and period</title>
<p>The default values are 1 restart per 5 seconds. This was chosen to
be safe for most systems, even with deep supervision hierarchies,
but you will probably want to tune the settings for your particular
use case.</p>
<p>First, the intensity decides how big bursts of restarts you want
to tolerate. For example, you might want to accept a burst of at
most 5 or 10 attempts, even within the same second, if it results
in a successful restart.</p>
<p>Second, you need to consider the sustained failure rate, if
crashes keep happening but not often enough to make the supervisor
give up. If you set intensity to 10 and set the period as low as 1,
the supervisor will allow child processes to keep restarting up to
10 times per second, forever, filling your logs with crash reports
until someone intervenes manually.</p>
<p>You should therefore set the period to be long enough that you can
accept that the supervisor keeps going at that rate. For example,
if you have picked an intensity value of 5, then setting the period
to 30 seconds will give you at most one restart per 6 seconds for
any longer period of time, which means that your logs won't fill up
too quickly, and you will have a chance to observe the failures and
apply a fix.</p>
<p>These choices depend a lot on your problem domain. If you don't
have real time monitoring and ability to fix problems quickly, for
example in an embedded system, you might want to accept at most
one restart per minute before the supervisor should give up and
escalate to the next level to try to clear the error automatically.
On the other hand, if it is more important that you keep trying
even at a high failure rate, you might want a sustained rate of as
much as 1-2 restarts per second.</p>
<p>Avoiding common mistakes:</p>
<list type="bulleted">
<item>
<p>Do not forget to consider the burst rate. If you set intensity
to 1 and period to 6, it gives the same sustained error rate as
5/30 or 10/60, but will not allow even 2 restart attempts in
quick succession. This is probably not what you wanted.</p>
</item>
<item>
<p>Do not set the period to a very high value if you want to
tolerate bursts. If you set intensity to 5 and period to 3600
(one hour), the supervisor will allow a short burst of 5
restarts, but then gives up if it sees another single restart
almost an hour later. You probably want to regard those crashes
as separate incidents, so setting the period to 5 or 10 minutes
will be more reasonable.</p>
</item>
<item>
<p>If your application has multiple levels of supervision, then
do not simply set the restart intensities to the same values on
all levels. Keep in mind that the total number of restarts
(before the top level supervisor gives up and terminates the
application) will be the product of the intensity values of all
the supervisors above the failing child process.</p>
<p>For example, if the top level allows 10 restarts, and the next
level also allows 10, a crashing child below that level will be
restarted 100 times, which is probably excessive. Allowing at
most 3 restarts for the top level supervisor might be a better
choice in this case.</p>
</item>
</list>
</section>
</section>
<section>
<title>Automatic Shutdown</title>
<p>A supervisor can be configured to automatically shut itself down when
<seeguide marker="#significant_child">significant children</seeguide>
terminate.</p>
<p>This is useful when a supervisor represents a work unit
of cooperating children, as opposed to independent workers. When
the work unit has finished its work, that is, when any or all
significant child processes have terminated, the supervisor
should then shut down by terminating all remaining child
processes in reverse start order according to the respective shutdown
specifications, and then itself.</p>
<p>Automatic shutdown is specified by the <c>auto_shutdown</c> key in the
supervisor flags map returned by the callback function <c>init</c>:</p>
<code type="none">
SupFlags = #{auto_shutdown => AutoShutdown, ...}</code>
<p>The <c>auto_shutdown</c> key is optional in this map. If it is not
given, it defaults to <c>never</c>.</p>
<note>
<p>The automatic shutdown facility only applies when significant children
terminate by themselves, that is, when their termination was not
caused by means of the supervisor. Specifically, neither the
termination of a child as a consequence of a sibling's death in the
<c>one_for_all</c> or <c>rest_for_one</c> strategies nor the manual
termination of a child by means of <c>supervisor:terminate_child/2</c>
will trigger an automatic shutdown.</p>
</note>
<section>
<title>never</title>
<p>Automatic shutdown is disabled.</p>
<p>In this mode, significant children are not accepted. If the
child specs returned from <c>init</c> contains significant
children, the supervisor will refuse to start. Attempts to
start significant children dynamically will be rejected.</p>
<p>This is the default setting.</p>
</section>
<section>
<title>any_significant</title>
<p>The supervisor will automatically shut itself down when
<em>any</em> significant child terminates, that is, when a
transient significant child terminates normally or when a
temporary significant child terminates normally or
abnormally.</p>
</section>
<section>
<title>all_significant</title>
<p>The supervisor will automatically shut itself down when
<em>all</em> significant children have terminated, that is,
when the <em>last active</em> significant child terminates.
The same rules as for <c>any_significant</c> apply.</p>
</section>
<warning>
<p>The automatic shutdown feature appeared in OTP 24.0, but
applications using this feature will also compile and
run with older OTP versions.</p>
<p>However, such applications, when compiled with an OTP version
that predates the appearance of the automatic shutdown feature,
will leak processes because the automatic shutdowns they rely
on will not happen.</p>
<p>It is up to implementors to take proper precautions if they
expect that their applications may be compiled with older OTP
versions.</p>
</warning>
<warning>
<p>Top supervisors of <seeguide marker="applications">Applications</seeguide>
should not be configured for automatic shutdown, because when the top
supervisor exits, the application terminates. If the application is
<c>permanent</c>, all other applications and the runtime system
are terminated, also.</p>
</warning>
<warning>
<p>Supervisors configured for automatic shutdown should not be
made <seeguide marker="#restart">permanent</seeguide> children
of their respective parent supervisors, as they would be restarted
immediately after having automatically shut down, only to shut down
automatically again after a while, and may thus exhaust the
<seeguide marker="#max_intensity">Maximum Restart Intensity</seeguide>
of the parent supervisor.</p>
</warning>
</section>
<section>
<marker id="spec"></marker>
<title>Child Specification</title>
<p>The type definition for a child specification is as follows:</p>
<code type="none"><![CDATA[
child_spec() = #{id => child_id(), % mandatory
start => mfargs(), % mandatory
restart => restart(), % optional
significant => significant(), % optional
shutdown => shutdown(), % optional
type => worker(), % optional
modules => modules()} % optional
child_id() = term()
mfargs() = {M :: module(), F :: atom(), A :: [term()]}
modules() = [module()] | dynamic
restart() = permanent | transient | temporary
significant() = boolean()
shutdown() = brutal_kill | timeout()
worker() = worker | supervisor]]></code>
<list type="bulleted">
<item>
<p><c>id</c> is used to identify the child
specification internally by the supervisor.</p>
<p>The <c>id</c> key is mandatory.</p>
<p>Note that this identifier occasionally has been called
"name". As far as possible, the terms "identifier" or "id"
are now used but in order to keep backwards compatibility,
some occurrences of "name" can still be found, for example
in error messages.</p>
</item>
<item>
<p><c>start</c> defines the function call used to start
the child process. It is a module-function-arguments tuple
used as <c>apply(M, F, A)</c>.</p>
<p>It is to be (or result in) a call to any of the following:</p>
<list type="bulleted">
<item><c>supervisor:start_link</c></item>
<item><c>gen_server:start_link</c></item>
<item><c>gen_statem:start_link</c></item>
<item><c>gen_event:start_link</c></item>
<item>A function compliant with these functions. For details,
see the <c>supervisor(3)</c> manual page.</item>
</list>
<p>The <c>start</c> key is mandatory.</p>
</item>
<item>
<marker id="restart"></marker>
<p><c>restart</c> defines when a terminated child process is to
be restarted.</p>
<list type="bulleted">
<item>A <c>permanent</c> child process is always restarted.</item>
<item>A <c>temporary</c> child process is never restarted
(not even when the supervisor restart strategy
is <c>rest_for_one</c> or <c>one_for_all</c> and a sibling
death causes the temporary process to be terminated).</item>
<item>A <c>transient</c> child process is restarted only if it
terminates abnormally, that is, with an exit reason other than
<c>normal</c>, <c>shutdown</c>, or <c>{shutdown,Term}</c>.</item>
</list>
<p>The <c>restart</c> key is optional. If it is not given, the
default value <c>permanent</c> will be used.</p>
</item>
<item>
<marker id="significant_child"></marker>
<p><c>significant</c> defines if a child is considered significant
for <seeguide marker="#automatic-shutdown">automatic
self-shutdown</seeguide> of the supervisor.</p>
<p>It is invalid to set this option to <c>true</c> for a child
with <seeguide marker="#restart">restart type</seeguide>
<c>permanent</c> or in a supervisor with
<seeguide marker="#automatic-shutdown">auto_shutdown</seeguide>
set to <c>never</c>.</p>
</item>
<item>
<marker id="shutdown"></marker>
<p><c>shutdown</c> defines how a child process is to be
terminated.</p>
<list type="bulleted">
<item><c>brutal_kill</c> means that the child process is
unconditionally terminated using <c>exit(Child, kill)</c>.</item>
<item>An integer time-out value means that the supervisor tells
the child process to terminate by calling
<c>exit(Child, shutdown)</c> and then waits for an exit
signal back. If no exit signal is received within
the specified time, the child process is unconditionally
terminated using <c>exit(Child, kill)</c>.</item>
<item>If the child process is another supervisor, it must be
set to <c>infinity</c> to give the subtree enough time to
shut down. It is also allowed to set it to <c>infinity</c>,
if the child process is a worker. See the warning below:</item>
</list>
<warning>
<p>Setting the shutdown time to anything other
than <c>infinity</c> for a child of type <c>supervisor</c>
can cause a race condition where the child in question
unlinks its own children, but fails to terminate them
before it is killed.</p>
<p>Be careful when setting the shutdown time to
<c>infinity</c> when the child process is a worker. Because, in this
situation, the termination of the supervision tree depends on the
child process; it must be implemented in a safe way and its cleanup
procedure must always return.</p>
</warning>
<p>The <c>shutdown</c> key is optional. If it is not given,
and the child is of type <c>worker</c>, the default value
<c>5000</c> will be used; if the child is of type
<c>supervisor</c>, the default value <c>infinity</c> will be
used.</p>
</item>
<item>
<p><c>type</c> specifies if the child process is a supervisor or
a worker.</p>
<p>The <c>type</c> key is optional. If it is not given, the
default value <c>worker</c> will be used.</p>
</item>
<item>
<p><c>modules</c> are to be a list with one element
<c>[Module]</c>, where <c>Module</c> is the name of
the callback module, if the child process is a supervisor,
gen_server, gen_statem.
If the child process is a gen_event,
the value shall be <c>dynamic</c>.</p>
<p>This information is used by the release handler during
upgrades and downgrades, see
<seeguide marker="release_handling">Release Handling</seeguide>.</p>
<p>The <c>modules</c> key is optional. If it is not given, it
defaults to <c>[M]</c>, where <c>M</c> comes from the
child's start <c>{M,F,A}</c>.</p>
</item>
</list>
<p><em>Example:</em> The child specification to start the server
<c>ch3</c> in the previous example look as follows:</p>
<code type="none">
#{id => ch3,
start => {ch3, start_link, []},
restart => permanent,
shutdown => brutal_kill,
type => worker,
modules => [ch3]}</code>
<p>or simplified, relying on the default values:</p>
<code type="none">
#{id => ch3,
start => {ch3, start_link, []}
shutdown => brutal_kill}</code>
<p>Example: A child specification to start the event manager from
the chapter about
<seeguide marker="events#mgr">gen_event</seeguide>:</p>
<code type="none">
#{id => error_man,
start => {gen_event, start_link, [{local, error_man}]},
modules => dynamic}</code>
<p>Both server and event manager are registered processes which
can be expected to be always accessible. Thus they are
specified to be <c>permanent</c>.</p>
<p><c>ch3</c> does not need to do any cleaning up before
termination. Thus, no shutdown time is needed, but
<c>brutal_kill</c> is sufficient. <c>error_man</c> can
need some time for the event handlers to clean up, thus
the shutdown time is set to 5000 ms (which is the default
value).</p>
<p>Example: A child specification to start another supervisor:</p>
<code type="none">
#{id => sup,
start => {sup, start_link, []},
restart => transient,
type => supervisor} % will cause default shutdown=>infinity</code>
</section>
<section>
<marker id="super_tree"></marker>
<title>Starting a Supervisor</title>
<p>In the previous example, the supervisor is started by calling
<c>ch_sup:start_link()</c>:</p>
<code type="none">
start_link() ->
supervisor:start_link(ch_sup, []).</code>
<p><c>ch_sup:start_link</c> calls function
<c>supervisor:start_link/2</c>, which spawns and links to a new
process, a supervisor.</p>
<list type="bulleted">
<item>The first argument, <c>ch_sup</c>, is the name of
the callback module, that is, the module where the <c>init</c>
callback function is located.</item>
<item>The second argument, <c>[]</c>, is a term that is passed
as is to
the callback function <c>init</c>. Here, <c>init</c> does not
need any indata and ignores the argument.</item>
</list>
<p>In this case, the supervisor is not registered. Instead its pid
must be used. A name can be specified by calling
<c>supervisor:start_link({local, Name}, Module, Args)</c> or
<c>supervisor:start_link({global, Name}, Module, Args)</c>.</p>
<p>The new supervisor process calls the callback function
<c>ch_sup:init([])</c>. <c>init</c> shall return
<c>{ok, {SupFlags, ChildSpecs}}</c>:</p>
<code type="none">
init(_Args) ->
SupFlags = #{},
ChildSpecs = [#{id => ch3,
start => {ch3, start_link, []},
shutdown => brutal_kill}],
{ok, {SupFlags, ChildSpecs}}.</code>
<p>The supervisor then starts all its child processes according to
the child specifications in the start specification. In this case
there is one child process, <c>ch3</c>.</p>
<p><c>supervisor:start_link</c> is synchronous. It does
not return until all child processes have been started.</p>
</section>
<section>
<title>Adding a Child Process</title>
<p>In addition to the static supervision tree, dynamic child
processes can be added to an existing supervisor with the following
call:</p>
<code type="none">
supervisor:start_child(Sup, ChildSpec)</code>
<p><c>Sup</c> is the pid, or name, of the supervisor.
<c>ChildSpec</c> is a
<seeguide marker="#spec">child specification</seeguide>.</p>
<p>Child processes added using <c>start_child/2</c> behave in
the same way as the other child processes, with the an important
exception: if a supervisor dies and is recreated, then
all child processes that were dynamically added to the supervisor
are lost.</p>
</section>
<section>
<title>Stopping a Child Process</title>
<p>Any child process, static or dynamic, can be stopped in
accordance with the shutdown specification:</p>
<code type="none">
supervisor:terminate_child(Sup, Id)</code>
<p>Stopping a <seeguide marker="#significant_child">significant
child</seeguide> of a supervisor configured for
<seeguide marker="#automatic-shutdown">automatic shutdown</seeguide>
will not trigger an automatic shutdown.</p>
<p>The child specification for a stopped child process is deleted
with the following call:</p>
<code type="none">
supervisor:delete_child(Sup, Id)</code>
<p><c>Sup</c> is the pid, or name, of the supervisor.
<c>Id</c> is the value associated with the <c>id</c> key in
the <seeguide marker="#spec">child specification</seeguide>.</p>
<p>As with dynamically added child processes, the effects of
deleting a static child process are lost if the supervisor itself
restarts.</p>
</section>
<section>
<marker id="simple"/>
<title>Simplified one_for_one Supervisors</title>
<p>A supervisor with restart strategy <c>simple_one_for_one</c> is
a simplified <c>one_for_one</c> supervisor, where all child
processes are dynamically added instances of the same process.</p>
<p>The following is an example of a callback module for a
<c>simple_one_for_one</c> supervisor:</p>
<code type="none">
-module(simple_sup).
-behaviour(supervisor).
-export([start_link/0]).
-export([init/1]).
start_link() ->
supervisor:start_link(simple_sup, []).
init(_Args) ->
SupFlags = #{strategy => simple_one_for_one,
intensity => 0,
period => 1},
ChildSpecs = [#{id => call,
start => {call, start_link, []},
shutdown => brutal_kill}],
{ok, {SupFlags, ChildSpecs}}.</code>
<p>When started, the supervisor does not start any child processes.
Instead, all child processes are added dynamically by calling:</p>
<code type="none">
supervisor:start_child(Sup, List)</code>
<p><c>Sup</c> is the pid, or name, of the supervisor.
<c>List</c> is an arbitrary list of terms, which are added to
the list of arguments specified in the child specification. If
the start function is specified as <c>{M, F, A}</c>,
the child process is started by calling
<c>apply(M, F, A++List)</c>.</p>
<p>For example, adding a child to <c>simple_sup</c> above:</p>
<code type="none">
supervisor:start_child(Pid, [id1])</code>
<p>The result is that the child process is started by calling
<c>apply(call, start_link, []++[id1])</c>, or actually:</p>
<code type="none">
call:start_link(id1)</code>
<p>A child under a <c>simple_one_for_one</c> supervisor can be
terminated with the following:</p>
<code type="none">
supervisor:terminate_child(Sup, Pid)</code>
<p><c>Sup</c> is the pid, or name, of the supervisor and
<c>Pid</c> is the pid of the child.</p>
<p>Because a <c>simple_one_for_one</c> supervisor can have many
children, it shuts them all down asynchronously. This means that
the children will do their cleanup in parallel and therefore the
order in which they are stopped is not defined.</p>
</section>
<section>
<title>Stopping</title>
<p>Since the supervisor is part of a supervision tree, it is
automatically terminated by its supervisor. When asked to
shut down, it terminates all child processes in reversed start
order according to the respective shutdown specifications, and
then terminates itself.</p>
<p>If the supervisor is configured for
<seeguide marker="#automatic-shutdown">automatic
shutdown</seeguide> on termination of any or all
<seeguide marker="#significant_child">significant children</seeguide>,
it will shut down itself when any or the last active significant
child terminates, respectively. The shutdown itself follows
the same procedure as described above, that is, the supervisor
terminates all remaining child processes in reversed start
order, and then terminates itself.</p>
<section>
<title>Manual stopping versus Automatic Shutdown</title>
<p>For several reasons, a supervisor should not be stopped
manually via <seemfa marker="stdlib:supervisor#terminate_child/2">
<c>supervisor:terminate_child/2</c></seemfa> from a child located
in its own tree.</p>
<list type="ordered">
<item>
<p>The child process will have to know the pids or registered
names not only of the supervisor it wants to stop, but also
that of the supervisor's parent supervisor, in order to tell
the parent supervisor to stop the supervisor it wants to stop.
This can make restructuring a supervision tree difficult.</p>
</item>
<item>
<p><seemfa marker="stdlib:supervisor#terminate_child/2">
<c>supervisor:terminate_child/2</c></seemfa> is a blocking
call that will only return after the parent supervisor has
finished the shutdown of the supervisor that should be stopped.
Unless the call is made from a spawned process, this will
result in a deadlock, as the supervisor waits for the child
to exit as part of its shutdown procedure, whereas the
child waits for the supervisor to shut down. If the child is
trapping exits, this deadlock will last until the
<seeguide marker="#shutdown">shutdown</seeguide>
timeout for the child expires.</p>
</item>
<item>
<p>When a supervisor is stopping a child, it will wait for the
shutdown to complete before accepting other calls, that is,
the supervisor will be unresponsive until then. If the
termination takes some time to complete, especially when
the considerations outlined in the previous point were not
taken into account carefully, said supervisor might become
unresponsive for a long time.</p>
</item>
</list>
<p>Instead, it is generally a better approach to rely on
<seeguide marker="#automatic-shutdown">Automatic
Shutdown</seeguide>.</p>
<list type="ordered">
<item>
<p>A child process does not need to know anything about its
supervisor and its respective parent, not even that it is
part of a supervision tree in the first place. It is instead
only the supervisor which hosts the child who must know
which of its children are
<seeguide marker="#significant_child">significant</seeguide>
ones, and when to shut itself down.</p>
</item>
<item>
<p>A child process does not need to do anything special to
shut down the work unit it is part of. All it needs to do
is terminate normally when it has finished the task it was
started for.</p>
</item>
<item>
<p>A supervisor that is automatically shutting itself down
will perform the required shutdown steps fully independent
of its parent supervisor. The parent supervisor will only
notice that its child supervisor has terminated in the end.
As the parent supervisor is not involved in the shutdown
process, it will not be blocked.</p>
</item>
</list>
</section>
</section>
</chapter>
|