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
13       behaviors.  A  supervisor  implemented using this module has a standard
14       set of interface functions and include functionality  for  tracing  and
15       error  reporting.  Supervisors are used to build a hierarchical process
16       structure called a supervision tree, a nice way to structure  a  fault-
17       tolerant  application.  For more information, see  Supervisor Behaviour
18       in OTP 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
82       defined  using  two  integer  values  specified with keys intensity and
83       period in the above map. Assuming the values  MaxR  for  intensity  and
84       MaxT  for  period,  then,  if more than MaxR restarts occur within MaxT
85       seconds, the supervisor terminates all child processes and then itself.
86       The  termination  reason for the supervisor itself in that case will be
87       shutdown. 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
113           apply(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
118           supervisor.
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
126           tuple {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
228              internally in supervisor. If the restart type of  the  child  is
229              temporary,  the  process  is never to be restarted and therefore
230              there is no need to store the real argument  list.  Value  unde‐
231              fined is then stored instead.
232
233       modules() = [module()] | dynamic
234
235       restart() = permanent | transient | temporary
236
237       shutdown() = brutal_kill | timeout()
238
239       strategy() =
240           one_for_all | one_for_one | rest_for_one | simple_one_for_one
241
242       sup_flags() =
243           #{strategy => strategy(),
244             intensity => integer() >= 0,
245             period => integer() >= 1} |
246           {RestartStrategy :: strategy(),
247            Intensity :: integer() >= 0,
248            Period :: integer() >= 1}
249
250              The  tuple format is kept for backward compatibility only. A map
251              is preferred; see more details above.
252
253       sup_ref() =
254           (Name :: atom()) |
255           {Name :: atom(), Node :: node()} |
256           {global, Name :: atom()} |
257           {via, Module :: module(), Name :: any()} |
258           pid()
259
260       worker() = worker | supervisor
261

EXPORTS

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

CALLBACK FUNCTIONS

601       The following function must be exported from a supervisor callback mod‐
602       ule.
603

EXPORTS

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

SEE ALSO

642       gen_event(3), gen_statem(3), gen_server(3), sys(3)
643
644
645
646Ericsson AB                       stdlib 3.10                    supervisor(3)
Impressum