1supervisor(3)              Erlang Module Definition              supervisor(3)
2
3
4

NAME

6       supervisor - Generic supervisor behavior.
7

DESCRIPTION

9       This  behavior  module provides a supervisor, a process that supervises
10       other processes called child processes. A child process can  either  be
11       another  supervisor  or a worker process. Worker processes are normally
12       implemented using one of the gen_event, gen_server, or  gen_statem  be‐
13       haviors.  A supervisor implemented using this module has a standard set
14       of interface functions and include functionality for tracing and  error
15       reporting.  Supervisors are used to build a hierarchical process struc‐
16       ture called a supervision tree, a nice way to structure a  fault-toler‐
17       ant application. For more information, see  Supervisor Behaviour in OTP
18       Design Principles.
19
20       A supervisor expects the definition of which child processes to  super‐
21       vise to be specified in a callback module exporting a predefined set of
22       functions.
23
24       Unless otherwise stated, all functions in this module fail if the spec‐
25       ified supervisor does not exist or if bad arguments are specified.
26

SUPERVISION PRINCIPLES

28       The  supervisor  is  responsible for starting, stopping, and monitoring
29       its child processes. The basic idea of a supervisor  is  that  it  must
30       keep its child processes alive by restarting them when necessary.
31
32       The  children of a supervisor are defined as a list of child specifica‐
33       tions. When the supervisor is started, the child processes are  started
34       in order from left to right according to this list. When the supervisor
35       terminates, it first terminates its child processes in  reversed  start
36       order, from right to left.
37
38       The supervisor properties are defined by the supervisor flags. The type
39       definition for the supervisor flags is as follows:
40
41       sup_flags() = #{strategy => strategy(),         % optional
42                       intensity => non_neg_integer(), % optional
43                       period => pos_integer()}        % optional
44
45       A supervisor can have one of the following restart strategies specified
46       with the strategy key in the above map:
47
48         * one_for_one  -  If  one  child  process  terminates  and  is  to be
49           restarted, only that child process is affected. This is the default
50           restart strategy.
51
52         * one_for_all  -  If  one  child  process  terminates  and  is  to be
53           restarted, all other child processes are terminated  and  then  all
54           child processes are restarted.
55
56         * rest_for_one  -  If  one  child  process  terminates  and  is to be
57           restarted, the 'rest' of the child processes (that  is,  the  child
58           processes  after  the  terminated child process in the start order)
59           are terminated. Then the terminated child  process  and  all  child
60           processes after it are restarted.
61
62         * simple_one_for_one - A simplified one_for_one supervisor, where all
63           child processes are dynamically added instances of the same process
64           type, that is, running the same code.
65
66           Functions  delete_child/2  and restart_child/2 are invalid for sim‐
67           ple_one_for_one supervisors and  return  {error,simple_one_for_one}
68           if the specified supervisor uses this restart strategy.
69
70           Function  terminate_child/2  can  be  used  for children under sim‐
71           ple_one_for_one supervisors by specifying the child's pid() as  the
72           second  argument.  If instead the child specification identifier is
73           used, terminate_child/2 return {error,simple_one_for_one}.
74
75           As a simple_one_for_one supervisor can have many children, it shuts
76           them all down asynchronously. This means that the children do their
77           cleanup in parallel, and therefore the  order  in  which  they  are
78           stopped is not defined.
79
80       To  prevent  a  supervisor  from getting into an infinite loop of child
81       process terminations and restarts, a maximum restart intensity  is  de‐
82       fined using two integer values specified with keys intensity and period
83       in the above map. Assuming the values MaxR for intensity and  MaxT  for
84       period, then, if more than MaxR restarts occur within MaxT seconds, the
85       supervisor terminates all child processes and then itself. The termina‐
86       tion  reason  for  the supervisor itself in that case will be shutdown.
87       intensity defaults to 1 and period defaults to 5.
88
89       The type definition of a child specification is as follows:
90
91       child_spec() = #{id => child_id(),       % mandatory
92                        start => mfargs(),      % mandatory
93                        restart => restart(),   % optional
94                        shutdown => shutdown(), % optional
95                        type => worker(),       % optional
96                        modules => modules()}   % optional
97
98       The  old  tuple  format  is  kept  for  backwards  compatibility,   see
99       child_spec(), but the map is preferred.
100
101         * id  is  used  to identify the child specification internally by the
102           supervisor.
103
104           The id key is mandatory.
105
106           Notice that this identifier on occations has been called "name". As
107           far as possible, the terms "identifier" or "id" are now used but to
108           keep backward compatibility, some occurences of "name" can still be
109           found, for example in error messages.
110
111         * start defines the function call used to start the child process. It
112           must be a  module-function-arguments  tuple  {M,F,A}  used  as  ap‐
113           ply(M,F,A).
114
115           The  start  function must create and link to the child process, and
116           must return {ok,Child} or {ok,Child,Info}, where Child is  the  pid
117           of  the  child process and Info any term that is ignored by the su‐
118           pervisor.
119
120           The start function can also return ignore if the child process  for
121           some  reason  cannot be started, in which case the child specifica‐
122           tion is kept by the supervisor (unless it is a temporary child) but
123           the non-existing child process is ignored.
124
125           If  something goes wrong, the function can also return an error tu‐
126           ple {error,Error}.
127
128           Notice that the start_link functions of the different behavior mod‐
129           ules fulfill the above requirements.
130
131           The start key is mandatory.
132
133         * restart  defines when a terminated child process must be restarted.
134           A permanent child process is always restarted.  A  temporary  child
135           process  is  never  restarted  (even  when the supervisor's restart
136           strategy is rest_for_one  or  one_for_all  and  a  sibling's  death
137           causes  the  temporary process to be terminated). A transient child
138           process is restarted only if it  terminates  abnormally,  that  is,
139           with another exit reason than normal, shutdown, or {shutdown,Term}.
140
141           The restart key is optional. If it is not specified, it defaults to
142           permanent.
143
144         * shutdown defines how a  child  process  must  be  terminated.  bru‐
145           tal_kill means that the child process is unconditionally terminated
146           using exit(Child,kill). An integer time-out value  means  that  the
147           supervisor   tells  the  child  process  to  terminate  by  calling
148           exit(Child,shutdown) and then wait for an exit signal  with  reason
149           shutdown back from the child process. If no exit signal is received
150           within the specified number of milliseconds, the child  process  is
151           unconditionally terminated using exit(Child,kill).
152
153           If  the child process is another supervisor, the shutdown time must
154           be set to infinity to give the subtree ample time to shut down.
155
156     Warning:
157         Setting the shutdown time to anything other than infinity for a child
158         of  type  supervisor  can  cause  a race condition where the child in
159         question unlinks its own children, but fails to terminate them before
160         it is killed.
161
162
163           It is also allowed to set it to infinity, if the child process is a
164           worker.
165
166     Warning:
167         Be careful when setting the shutdown time to infinity when the  child
168         process  is  a worker. Because, in this situation, the termination of
169         the supervision tree depends on the child process, it must be  imple‐
170         mented in a safe way and its cleanup procedure must always return.
171
172
173           Notice  that all child processes implemented using the standard OTP
174           behavior modules automatically adhere to the shutdown protocol.
175
176           The shutdown key is optional. If it is not specified,  it  defaults
177           to  5000 if the child is of type worker and it defaults to infinity
178           if the child is of type supervisor.
179
180         * type specifies if the child process is a supervisor or a worker.
181
182           The type key is optional. If it is not specified,  it  defaults  to
183           worker.
184
185         * modules  is  used by the release handler during code replacement to
186           determine which processes are using a certain module. As a rule  of
187           thumb,  if  the  child  process  is  a  supervisor,  gen_server or,
188           gen_statem, this is to be a list with one element  [Module],  where
189           Module  is  the  callback  module. If the child process is an event
190           manager (gen_event) with a dynamic set of callback  modules,  value
191           dynamic  must be used. For more information about release handling,
192           see  Release Handling in OTP Design Principles.
193
194           The modules key is optional. If it is not specified, it defaults to
195           [M], where M comes from the child's start {M,F,A}.
196
197         * Internally, the supervisor also keeps track of the pid Child of the
198           child process, or undefined if no pid exists.
199

DATA TYPES

201       child() = undefined | pid()
202
203       child_id() = term()
204
205              Not a pid().
206
207       child_spec() =
208           #{id := child_id(),
209             start := mfargs(),
210             restart => restart(),
211             shutdown => shutdown(),
212             type => worker(),
213             modules => modules()} |
214           {Id :: child_id(),
215            StartFunc :: mfargs(),
216            Restart :: restart(),
217            Shutdown :: shutdown(),
218            Type :: worker(),
219            Modules :: modules()}
220
221              The tuple format is kept for backward compatibility only. A  map
222              is preferred; see more details above.
223
224       mfargs() =
225           {M :: module(), F :: atom(), A :: [term()] | undefined}
226
227              Value undefined for A (the argument list) is only to be used in‐
228              ternally in supervisor. If the restart type of the child is tem‐
229              porary, the process is never to be restarted and therefore there
230              is no need to store the real argument list. Value  undefined  is
231              then stored instead.
232
233       modules() = [module()] | dynamic
234
235       restart() = permanent | transient | temporary
236
237       shutdown() = brutal_kill | timeout()
238
239       startchild_err() =
240           already_present | {already_started, Child :: child()} | term()
241
242       startchild_ret() =
243           {ok, Child :: child()} |
244           {ok, Child :: child(), Info :: term()} |
245           {error, startchild_err()}
246
247       startlink_err() =
248           {already_started, pid()} | {shutdown, term()} | term()
249
250       startlink_ret() =
251           {ok, pid()} | ignore | {error, startlink_err()}
252
253       strategy() =
254           one_for_all | one_for_one | rest_for_one | simple_one_for_one
255
256       sup_flags() =
257           #{strategy => strategy(),
258             intensity => integer() >= 0,
259             period => integer() >= 1} |
260           {RestartStrategy :: strategy(),
261            Intensity :: integer() >= 0,
262            Period :: integer() >= 1}
263
264              The  tuple format is kept for backward compatibility only. A map
265              is preferred; see more details above.
266
267       sup_ref() =
268           (Name :: atom()) |
269           {Name :: atom(), Node :: node()} |
270           {global, Name :: atom()} |
271           {via, Module :: module(), Name :: any()} |
272           pid()
273
274       worker() = worker | supervisor
275

EXPORTS

277       check_childspecs(ChildSpecs) -> Result
278
279              Types:
280
281                 ChildSpecs = [child_spec()]
282                 Result = ok | {error, Error :: term()}
283
284              Takes a list of child specification as argument and  returns  ok
285              if  all  of them are syntactically correct, otherwise {error,Er‐
286              ror}.
287
288       count_children(SupRef) -> PropListOfCounts
289
290              Types:
291
292                 SupRef = sup_ref()
293                 PropListOfCounts = [Count]
294                 Count =
295                     {specs, ChildSpecCount :: integer() >= 0} |
296                     {active, ActiveProcessCount :: integer() >= 0} |
297                     {supervisors, ChildSupervisorCount :: integer() >= 0} |
298                     {workers, ChildWorkerCount :: integer() >= 0}
299
300              Returns a property list (see proplists)  containing  the  counts
301              for  each  of  the  following elements of the supervisor's child
302              specifications and managed processes:
303
304                * specs - The total count of children, dead or alive.
305
306                * active - The count of all actively running  child  processes
307                  managed  by this supervisor. For a simple_one_for_one super‐
308                  visors, no check is done to ensure that each  child  process
309                  is  still alive, although the result provided here is likely
310                  to be very accurate unless the supervisor is  heavily  over‐
311                  loaded.
312
313                * supervisors - The count of all children marked as child_type
314                  = supervisor in the specification list,  regardless  if  the
315                  child process is still alive.
316
317                * workers  -  The count of all children marked as child_type =
318                  worker in the specification list, regardless  if  the  child
319                  process is still alive.
320
321              For a description of SupRef, see start_child/2.
322
323       delete_child(SupRef, Id) -> Result
324
325              Types:
326
327                 SupRef = sup_ref()
328                 Id = child_id()
329                 Result = ok | {error, Error}
330                 Error = running | restarting | not_found | simple_one_for_one
331
332              Tells  supervisor SupRef to delete the child specification iden‐
333              tified by Id. The corresponding child process must not  be  run‐
334              ning. Use terminate_child/2 to terminate it.
335
336              For a description of SupRef, see start_child/2.
337
338              If  successful, the function returns ok. If the child specifica‐
339              tion identified by Id exists but the corresponding child process
340              is  running  or  is  about to be restarted, the function returns
341              {error,running}  or  {error,restarting},  respectively.  If  the
342              child  specification  identified by Id does not exist, the func‐
343              tion returns {error,not_found}.
344
345       get_childspec(SupRef, Id) -> Result
346
347              Types:
348
349                 SupRef = sup_ref()
350                 Id = pid() | child_id()
351                 Result = {ok, child_spec()} | {error, Error}
352                 Error = not_found
353
354              Returns the child specification map for the child identified  by
355              Id  under supervisor SupRef. The returned map contains all keys,
356              both mandatory and optional.
357
358              For a description of SupRef, see start_child/2.
359
360       restart_child(SupRef, Id) -> Result
361
362              Types:
363
364                 SupRef = sup_ref()
365                 Id = child_id()
366                 Result =
367                     {ok, Child :: child()} |
368                     {ok, Child :: child(), Info :: term()} |
369                     {error, Error}
370                 Error =
371                     running | restarting | not_found |  simple_one_for_one  |
372                 term()
373
374              Tells supervisor SupRef to restart a child process corresponding
375              to the child specification identified by Id. The child  specifi‐
376              cation  must exist, and the corresponding child process must not
377              be running.
378
379              Notice that for temporary children, the child  specification  is
380              automatically deleted when the child terminates; thus, it is not
381              possible to restart such children.
382
383              For a description of SupRef, see start_child/2.
384
385              If the child specification identified by Id does not exist,  the
386              function  returns  {error,not_found}. If the child specification
387              exists but the corresponding process  is  already  running,  the
388              function returns {error,running}.
389
390              If  the  child  process  start  function  returns  {ok,Child} or
391              {ok,Child,Info}, the pid is added  to  the  supervisor  and  the
392              function returns the same value.
393
394              If  the child process start function returns ignore, the pid re‐
395              mains set to undefined and the function returns {ok,undefined}.
396
397              If the child process start function returns an error tuple or an
398              erroneous value, or if it fails, the function returns {error,Er‐
399              ror}, where Error is a term containing information about the er‐
400              ror.
401
402       start_child(SupRef, ChildSpec) -> startchild_ret()
403
404              Types:
405
406                 SupRef = sup_ref()
407                 ChildSpec = child_spec() | (List :: [term()])
408                 startchild_ret() =
409                     {ok, Child :: child()} |
410                     {ok, Child :: child(), Info :: term()} |
411                     {error, startchild_err()}
412                 startchild_err() =
413                     already_present | {already_started, Child :: child()} | term()
414
415              Dynamically  adds  a  child  specification to supervisor SupRef,
416              which starts the corresponding child process.
417
418              SupRef can be any of the following:
419
420                * The pid
421
422                * Name, if the supervisor is locally registered
423
424                * {Name,Node}, if the supervisor is locally registered at  an‐
425                  other node
426
427                * {global,Name}, if the supervisor is globally registered
428
429                * {via,Module,Name},  if  the supervisor is registered through
430                  an alternative process registry
431
432              ChildSpec must be a valid child specification (unless the super‐
433              visor  is a simple_one_for_one supervisor; see below). The child
434              process is started by using the start function as defined in the
435              child specification.
436
437              For a simple_one_for_one supervisor, the child specification de‐
438              fined in Module:init/1 is used, and ChildSpec must instead be an
439              arbitrary  list of terms List. The child process is then started
440              by appending List to the existing start function arguments, that
441              is,  by calling apply(M, F, A++List), where {M,F,A} is the start
442              function defined in the child specification.
443
444                * If there already exists a child specification with the spec‐
445                  ified  identifier,  ChildSpec is discarded, and the function
446                  returns     {error,already_present}      or      {error,{al‐
447                  ready_started,Child}},  depending  on  if  the corresponding
448                  child process is running or not.
449
450                * If the child process start function  returns  {ok,Child}  or
451                  {ok,Child,Info},  the  child specification and pid are added
452                  to the supervisor and the function returns the same value.
453
454                * If the child process  start  function  returns  ignore,  the
455                  child  specification  is added to the supervisor (unless the
456                  supervisor is a simple_one_for_one supervisor,  see  below),
457                  the  pid  is  set  to  undefined,  and  the function returns
458                  {ok,undefined}.
459
460              For a simple_one_for_one supervisor, when a child process  start
461              function  returns  ignore,  the functions returns {ok,undefined}
462              and no child is added to the supervisor.
463
464              If the child process start function returns an error tuple or an
465              erroneous value, or if it fails, the child specification is dis‐
466              carded, and the function returns {error,Error}, where Error is a
467              term containing information about the error and child specifica‐
468              tion.
469
470       start_link(Module, Args) -> startlink_ret()
471
472       start_link(SupName, Module, Args) -> startlink_ret()
473
474              Types:
475
476                 SupName = sup_name()
477                 Module = module()
478                 Args = term()
479                 startlink_ret() =
480                     {ok, pid()} | ignore | {error, startlink_err()}
481                 startlink_err() =
482                     {already_started, pid()} | {shutdown, term()} | term()
483                 sup_name() =
484                     {local, Name :: atom()} |
485                     {global, Name :: atom()} |
486                     {via, Module :: module(), Name :: any()}
487
488              Creates a supervisor process as part of a supervision tree.  For
489              example,  the  function ensures that the supervisor is linked to
490              the calling process (its supervisor).
491
492              The created supervisor process calls Module:init/1 to  find  out
493              about  restart  strategy,  maximum  restart intensity, and child
494              processes.  To  ensure   a   synchronized   startup   procedure,
495              start_link/2,3  does not return until Module:init/1 has returned
496              and all child processes have been started.
497
498                * If SupName={local,Name}, the supervisor  is  registered  lo‐
499                  cally as Name using register/2.
500
501                * If SupName={global,Name}, the supervisor is registered glob‐
502                  ally as Name using global:register_name/2.
503
504                * If SupName={via,Module,Name}, the supervisor  is  registered
505                  as Name using the registry represented by Module. The Module
506                  callback must export the functions register_name/2, unregis‐
507                  ter_name/1,  and  send/2,  which must behave like the corre‐
508                  sponding functions in global. Thus, {via,global,Name}  is  a
509                  valid reference.
510
511              If no name is provided, the supervisor is not registered.
512
513              Module is the name of the callback module.
514
515              Args  is  any  term  that  is  passed  as  the  argument to Mod‐
516              ule:init/1.
517
518                * If the supervisor and its child processes  are  successfully
519                  created  (that  is, if all child process start functions re‐
520                  turn {ok,Child}, {ok,Child,Info}, or ignore),  the  function
521                  returns {ok,Pid}, where Pid is the pid of the supervisor.
522
523                * If  there  already  exists a process with the specified Sup‐
524                  Name, the  function  returns  {error,{already_started,Pid}},
525                  where Pid is the pid of that process.
526
527                * If  Module:init/1  returns ignore, this function returns ig‐
528                  nore as well, and the supervisor terminates with reason nor‐
529                  mal.
530
531                * If  Module:init/1  fails or returns an incorrect value, this
532                  function returns {error,Term}, where Term is a term with in‐
533                  formation  about  the  error,  and the supervisor terminates
534                  with reason Term.
535
536                * If any child process start function fails or returns an  er‐
537                  ror tuple or an erroneous value, the supervisor first termi‐
538                  nates all already started child processes with reason  shut‐
539                  down  and  then  terminate itself and returns {error, {shut‐
540                  down, Reason}}.
541
542       terminate_child(SupRef, Id) -> Result
543
544              Types:
545
546                 SupRef = sup_ref()
547                 Id = pid() | child_id()
548                 Result = ok | {error, Error}
549                 Error = not_found | simple_one_for_one
550
551              Tells supervisor SupRef to terminate the specified child.
552
553              If the supervisor is not  simple_one_for_one,  Id  must  be  the
554              child  specification  identifier. The process, if any, is termi‐
555              nated and, unless it is a temporary child, the child  specifica‐
556              tion  is  kept by the supervisor. The child process can later be
557              restarted by the supervisor.  The  child  process  can  also  be
558              restarted    explicitly    by   calling   restart_child/2.   Use
559              delete_child/2 to remove the child specification.
560
561              If the child is temporary, the child specification is deleted as
562              soon  as  the process terminates. This means that delete_child/2
563              has no meaning and restart_child/2  cannot  be  used  for  these
564              children.
565
566              If the supervisor is simple_one_for_one, Id must be the pid() of
567              the child process. If the specified process is alive, but is not
568              a  child  of the specified supervisor, the function returns {er‐
569              ror,not_found}. If the child specification identifier is  speci‐
570              fied  instead  of  a  pid(),  the  function  returns {error,sim‐
571              ple_one_for_one}.
572
573              If successful, the function returns ok. If  there  is  no  child
574              specification  with  the specified Id, the function returns {er‐
575              ror,not_found}.
576
577              For a description of SupRef, see start_child/2.
578
579       which_children(SupRef) -> [{Id, Child, Type, Modules}]
580
581              Types:
582
583                 SupRef = sup_ref()
584                 Id = child_id() | undefined
585                 Child = child() | restarting
586                 Type = worker()
587                 Modules = modules()
588
589              Returns a newly created list with information  about  all  child
590              specifications  and  child  processes  belonging  to  supervisor
591              SupRef.
592
593              Notice that calling this function when supervising many children
594              under  low  memory  conditions can cause an out of memory excep‐
595              tion.
596
597              For a description of SupRef, see start_child/2.
598
599              The following information is given  for  each  child  specifica‐
600              tion/process:
601
602                * Id  - As defined in the child specification or undefined for
603                  a simple_one_for_one supervisor.
604
605                * Child - The pid of the corresponding child process, the atom
606                  restarting if the process is about to be restarted, or unde‐
607                  fined if there is no such process.
608
609                * Type - As defined in the child specification.
610
611                * Modules - As defined in the child specification.
612

CALLBACK FUNCTIONS

614       The following function must be exported from a supervisor callback mod‐
615       ule.
616

EXPORTS

618       Module:init(Args) -> Result
619
620              Types:
621
622                 Args = term()
623                 Result = {ok,{SupFlags,[ChildSpec]}} | ignore
624                  SupFlags = sup_flags()
625                  ChildSpec = child_spec()
626
627              Whenever  a  supervisor  is  started  using start_link/2,3, this
628              function is called by the new process to find out about  restart
629              strategy, maximum restart intensity, and child specifications.
630
631              Args is the Args argument provided to the start function.
632
633              SupFlags  is  the supervisor flags defining the restart strategy
634              and maximum restart intensity for the supervisor. [ChildSpec] is
635              a  list  of valid child specifications defining which child pro‐
636              cesses the supervisor must start and monitor. See the discussion
637              in section Supervision Principles earlier.
638
639              Notice that when the restart strategy is simple_one_for_one, the
640              list of child specifications must be a list with one child spec‐
641              ification only. (The child specification identifier is ignored.)
642              No child process  is  then  started  during  the  initialization
643              phase,  but  all  children are assumed to be started dynamically
644              using start_child/2.
645
646              The function can also return ignore.
647
648              Notice that this function can also be called as a part of a code
649              upgrade  procedure.  Therefore,  the function is not to have any
650              side effects. For more information about code upgrade of  super‐
651              visors,  see section Changing a Supervisor in OTP Design Princi‐
652              ples.
653

SEE ALSO

655       gen_event(3), gen_statem(3), gen_server(3), sys(3)
656
657
658
659Ericsson AB                     stdlib 3.14.2.1                  supervisor(3)
Impressum