1supervisor(3) Erlang Module Definition supervisor(3)
2
6 supervisor - Generic supervisor behavior.
7
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 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 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
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 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 The supervisor properties are defined by the supervisor flags. The type
39 definition for the supervisor flags is as follows:
40 sup_flags() = #{strategy => strategy(), % optional
42 intensity => non_neg_integer(), % optional
43 period => pos_integer()} % optional
44 A supervisor can have one of the following restart strategies specified
46 with the strategy key in the above map:
47 * 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 * 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 * 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 * 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 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 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 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 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 The type definition of a child specification is as follows:
90 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 The old tuple format is kept for backwards compatibility, see
99 child_spec(), but the map is preferred.
100 * id is used to identify the child specification internally by the
102 supervisor.
103 The id key is mandatory.
105 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 * 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 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 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 If something goes wrong, the function can also return an error
126 tuple {error,Error}.
127 Notice that the start_link functions of the different behavior mod‐
129 ules fulfill the above requirements.
130 The start key is mandatory.
132 * 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 The restart key is optional. If it is not specified, it defaults to
142 permanent.
143 * 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 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 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 It is also allowed to set it to infinity, if the child process is a
164 worker.
165 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 Notice that all child processes implemented using the standard OTP
174 behavior modules automatically adhere to the shutdown protocol.
175 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 * type specifies if the child process is a supervisor or a worker.
181 The type key is optional. If it is not specified, it defaults to
183 worker.
184 * 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 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 * Internally, the supervisor also keeps track of the pid Child of the
198 child process, or undefined if no pid exists.
199
201 child() = undefined | pid()
202 child_id() = term()
204 Not a pid().
206 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 The tuple format is kept for backward compatibility only. A map
222 is preferred; see more details above.
223 mfargs() =
225 {M :: module(), F :: atom(), A :: [term()] | undefined}
226 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 modules() = [module()] | dynamic
234 restart() = permanent | transient | temporary
236 shutdown() = brutal_kill | timeout()
238 startchild_err() =
240 already_present | {already_started, Child :: child()} | term()
241 startchild_ret() =
243 {ok, Child :: child()} |
244 {ok, Child :: child(), Info :: term()} |
245 {error, startchild_err()}
246 startlink_err() =
248 {already_started, pid()} | {shutdown, term()} | term()
249 startlink_ret() =
251 {ok, pid()} | ignore | {error, startlink_err()}
252 strategy() =
254 one_for_all | one_for_one | rest_for_one | simple_one_for_one
255 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 The tuple format is kept for backward compatibility only. A map
265 is preferred; see more details above.
266 sup_ref() =
268 (Name :: atom()) |
269 {Name :: atom(), Node :: node()} |
270 {global, Name :: atom()} |
271 {via, Module :: module(), Name :: any()} |
272 pid()
273 worker() = worker | supervisor
275
277 check_childspecs(ChildSpecs) -> Result
278 Types:
280 ChildSpecs = [child_spec()]
282 Result = ok | {error, Error :: term()}
283 Takes a list of child specification as argument and returns ok
285 if all of them are syntactically correct, otherwise
286 {error,Error}.
287 count_children(SupRef) -> PropListOfCounts
289 Types:
291 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 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 * specs - The total count of children, dead or alive.
305 * 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 * 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 * 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 For a description of SupRef, see start_child/2.
322 delete_child(SupRef, Id) -> Result
324 Types:
326 SupRef = sup_ref()
328 Id = child_id()
329 Result = ok | {error, Error}
330 Error = running | restarting | not_found | simple_one_for_one
331 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 For a description of SupRef, see start_child/2.
337 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 get_childspec(SupRef, Id) -> Result
346 Types:
348 SupRef = sup_ref()
350 Id = pid() | child_id()
351 Result = {ok, child_spec()} | {error, Error}
352 Error = not_found
353 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 For a description of SupRef, see start_child/2.
359 restart_child(SupRef, Id) -> Result
361 Types:
363 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 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 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 For a description of SupRef, see start_child/2.
384 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 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 If the child process start function returns ignore, the pid
395 remains set to undefined and the function returns {ok,unde‐
396 fined}.
397 If the child process start function returns an error tuple or an
399 erroneous value, or if it fails, the function returns
400 {error,Error}, where Error is a term containing information
401 about the error.
402 start_child(SupRef, ChildSpec) -> startchild_ret()
404 Types:
406 SupRef = sup_ref()
408 ChildSpec = child_spec() | (List :: [term()])
409 startchild_ret() =
410 {ok, Child :: child()} |
411 {ok, Child :: child(), Info :: term()} |
412 {error, startchild_err()}
413 startchild_err() =
414 already_present | {already_started, Child :: child()} | term()
415 Dynamically adds a child specification to supervisor SupRef,
417 which starts the corresponding child process.
418 SupRef can be any of the following:
420 * The pid
422 * Name, if the supervisor is locally registered
424 * {Name,Node}, if the supervisor is locally registered at
426 another node
427 * {global,Name}, if the supervisor is globally registered
429 * {via,Module,Name}, if the supervisor is registered through
431 an alternative process registry
432 ChildSpec must be a valid child specification (unless the super‐
434 visor is a simple_one_for_one supervisor; see below). The child
435 process is started by using the start function as defined in the
436 child specification.
437 For a simple_one_for_one supervisor, the child specification
439 defined in Module:init/1 is used, and ChildSpec must instead be
440 an arbitrary list of terms List. The child process is then
441 started by appending List to the existing start function argu‐
442 ments, that is, by calling apply(M, F, A++List), where {M,F,A}
443 is the start function defined in the child specification.
444 * If there already exists a child specification with the spec‐
446 ified identifier, ChildSpec is discarded, and the function
447 returns {error,already_present} or
448 {error,{already_started,Child}}, depending on if the corre‐
449 sponding child process is running or not.
450 * If the child process start function returns {ok,Child} or
452 {ok,Child,Info}, the child specification and pid are added
453 to the supervisor and the function returns the same value.
454 * If the child process start function returns ignore, the
456 child specification is added to the supervisor (unless the
457 supervisor is a simple_one_for_one supervisor, see below),
458 the pid is set to undefined, and the function returns
459 {ok,undefined}.
460 For a simple_one_for_one supervisor, when a child process start
462 function returns ignore, the functions returns {ok,undefined}
463 and no child is added to the supervisor.
464 If the child process start function returns an error tuple or an
466 erroneous value, or if it fails, the child specification is dis‐
467 carded, and the function returns {error,Error}, where Error is a
468 term containing information about the error and child specifica‐
469 tion.
470 start_link(Module, Args) -> startlink_ret()
472 start_link(SupName, Module, Args) -> startlink_ret()
474 Types:
476 SupName = sup_name()
478 Module = module()
479 Args = term()
480 startlink_ret() =
481 {ok, pid()} | ignore | {error, startlink_err()}
482 startlink_err() =
483 {already_started, pid()} | {shutdown, term()} | term()
484 sup_name() =
485 {local, Name :: atom()} |
486 {global, Name :: atom()} |
487 {via, Module :: module(), Name :: any()}
488 Creates a supervisor process as part of a supervision tree. For
490 example, the function ensures that the supervisor is linked to
491 the calling process (its supervisor).
492 The created supervisor process calls Module:init/1 to find out
494 about restart strategy, maximum restart intensity, and child
495 processes. To ensure a synchronized startup procedure,
496 start_link/2,3 does not return until Module:init/1 has returned
497 and all child processes have been started.
498 * If SupName={local,Name}, the supervisor is registered
500 locally as Name using register/2.
501 * If SupName={global,Name}, the supervisor is registered glob‐
503 ally as Name using global:register_name/2.
504 * If SupName={via,Module,Name}, the supervisor is registered
506 as Name using the registry represented by Module. The Module
507 callback must export the functions register_name/2, unregis‐
508 ter_name/1, and send/2, which must behave like the corre‐
509 sponding functions in global. Thus, {via,global,Name} is a
510 valid reference.
511 If no name is provided, the supervisor is not registered.
513 Module is the name of the callback module.
515 Args is any term that is passed as the argument to Mod‐
517 ule:init/1.
518 * If the supervisor and its child processes are successfully
520 created (that is, if all child process start functions
521 return {ok,Child}, {ok,Child,Info}, or ignore), the function
522 returns {ok,Pid}, where Pid is the pid of the supervisor.
523 * If there already exists a process with the specified Sup‐
525 Name, the function returns {error,{already_started,Pid}},
526 where Pid is the pid of that process.
527 * If Module:init/1 returns ignore, this function returns
529 ignore as well, and the supervisor terminates with reason
530 normal.
531 * If Module:init/1 fails or returns an incorrect value, this
533 function returns {error,Term}, where Term is a term with
534 information about the error, and the supervisor terminates
535 with reason Term.
536 * If any child process start function fails or returns an
538 error tuple or an erroneous value, the supervisor first ter‐
539 minates all already started child processes with reason
540 shutdown and then terminate itself and returns {error,
541 {shutdown, Reason}}.
542 terminate_child(SupRef, Id) -> Result
544 Types:
546 SupRef = sup_ref()
548 Id = pid() | child_id()
549 Result = ok | {error, Error}
550 Error = not_found | simple_one_for_one
551 Tells supervisor SupRef to terminate the specified child.
553 If the supervisor is not simple_one_for_one, Id must be the
555 child specification identifier. The process, if any, is termi‐
556 nated and, unless it is a temporary child, the child specifica‐
557 tion is kept by the supervisor. The child process can later be
558 restarted by the supervisor. The child process can also be
559 restarted explicitly by calling restart_child/2. Use
560 delete_child/2 to remove the child specification.
561 If the child is temporary, the child specification is deleted as
563 soon as the process terminates. This means that delete_child/2
564 has no meaning and restart_child/2 cannot be used for these
565 children.
566 If the supervisor is simple_one_for_one, Id must be the pid() of
568 the child process. If the specified process is alive, but is not
569 a child of the specified supervisor, the function returns
570 {error,not_found}. If the child specification identifier is
571 specified instead of a pid(), the function returns {error,sim‐
572 ple_one_for_one}.
573 If successful, the function returns ok. If there is no child
575 specification with the specified Id, the function returns
576 {error,not_found}.
577 For a description of SupRef, see start_child/2.
579 which_children(SupRef) -> [{Id, Child, Type, Modules}]
581 Types:
583 SupRef = sup_ref()
585 Id = child_id() | undefined
586 Child = child() | restarting
587 Type = worker()
588 Modules = modules()
589 Returns a newly created list with information about all child
591 specifications and child processes belonging to supervisor
592 SupRef.
593 Notice that calling this function when supervising many children
595 under low memory conditions can cause an out of memory excep‐
596 tion.
597 For a description of SupRef, see start_child/2.
599 The following information is given for each child specifica‐
601 tion/process:
602 * Id - As defined in the child specification or undefined for
604 a simple_one_for_one supervisor.
605 * Child - The pid of the corresponding child process, the atom
607 restarting if the process is about to be restarted, or unde‐
608 fined if there is no such process.
609 * Type - As defined in the child specification.
611 * Modules - As defined in the child specification.
613
615 The following function must be exported from a supervisor callback mod‐
616 ule.
617
619 Module:init(Args) -> Result
620 Types:
622 Args = term()
624 Result = {ok,{SupFlags,[ChildSpec]}} | ignore
625 SupFlags = sup_flags()
626 ChildSpec = child_spec()
627 Whenever a supervisor is started using start_link/2,3, this
629 function is called by the new process to find out about restart
630 strategy, maximum restart intensity, and child specifications.
631 Args is the Args argument provided to the start function.
633 SupFlags is the supervisor flags defining the restart strategy
635 and maximum restart intensity for the supervisor. [ChildSpec] is
636 a list of valid child specifications defining which child pro‐
637 cesses the supervisor must start and monitor. See the discussion
638 in section Supervision Principles earlier.
639 Notice that when the restart strategy is simple_one_for_one, the
641 list of child specifications must be a list with one child spec‐
642 ification only. (The child specification identifier is ignored.)
643 No child process is then started during the initialization
644 phase, but all children are assumed to be started dynamically
645 using start_child/2.
646 The function can also return ignore.
648 Notice that this function can also be called as a part of a code
650 upgrade procedure. Therefore, the function is not to have any
651 side effects. For more information about code upgrade of super‐
652 visors, see section Changing a Supervisor in OTP Design Princi‐
653 ples.
654
656 gen_event(3), gen_statem(3), gen_server(3), sys(3)
657Ericsson AB stdlib 3.14.1 supervisor(3)