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 is to
154 be set to infinity to give the subtree ample time to shut down. It
155 is also allowed to set it to infinity, if the child process is a
156 worker.
157 Warning:
159 Be careful when setting the shutdown time to infinity when the child
160 process is a worker. Because, in this situation, the termination of
161 the supervision tree depends on the child process, it must be imple‐
162 mented in a safe way and its cleanup procedure must always return.
163 Notice that all child processes implemented using the standard OTP
166 behavior modules automatically adhere to the shutdown protocol.
167 The shutdown key is optional. If it is not specified, it defaults
169 to 5000 if the child is of type worker and it defaults to infinity
170 if the child is of type supervisor.
171 * type specifies if the child process is a supervisor or a worker.
173 The type key is optional. If it is not specified, it defaults to
175 worker.
176 * modules is used by the release handler during code replacement to
178 determine which processes are using a certain module. As a rule of
179 thumb, if the child process is a supervisor, gen_server or,
180 gen_statem, this is to be a list with one element [Module], where
181 Module is the callback module. If the child process is an event
182 manager (gen_event) with a dynamic set of callback modules, value
183 dynamic must be used. For more information about release handling,
184 see Release Handling in OTP Design Principles.
185 The modules key is optional. If it is not specified, it defaults to
187 [M], where M comes from the child's start {M,F,A}.
188 * Internally, the supervisor also keeps track of the pid Child of the
190 child process, or undefined if no pid exists.
191
193 child() = undefined | pid()
194 child_id() = term()
196 Not a pid().
198 child_spec() =
200 #{id := child_id(),
201 start := mfargs(),
202 restart => restart(),
203 shutdown => shutdown(),
204 type => worker(),
205 modules => modules()} |
206 {Id :: child_id(),
207 StartFunc :: mfargs(),
208 Restart :: restart(),
209 Shutdown :: shutdown(),
210 Type :: worker(),
211 Modules :: modules()}
212 The tuple format is kept for backward compatibility only. A map
214 is preferred; see more details above.
215 mfargs() =
217 {M :: module(), F :: atom(), A :: [term()] | undefined}
218 Value undefined for A (the argument list) is only to be used
220 internally in supervisor. If the restart type of the child is
221 temporary, the process is never to be restarted and therefore
222 there is no need to store the real argument list. Value unde‐
223 fined is then stored instead.
224 modules() = [module()] | dynamic
226 restart() = permanent | transient | temporary
228 shutdown() = brutal_kill | timeout()
230 strategy() =
232 one_for_all | one_for_one | rest_for_one | simple_one_for_one
233 sup_flags() =
235 #{strategy => strategy(),
236 intensity => integer() >= 0,
237 period => integer() >= 1} |
238 {RestartStrategy :: strategy(),
239 Intensity :: integer() >= 0,
240 Period :: integer() >= 1}
241 The tuple format is kept for backward compatibility only. A map
243 is preferred; see more details above.
244 sup_ref() =
246 (Name :: atom()) |
247 {Name :: atom(), Node :: node()} |
248 {global, Name :: atom()} |
249 {via, Module :: module(), Name :: any()} |
250 pid()
251 worker() = worker | supervisor
253
255 check_childspecs(ChildSpecs) -> Result
256 Types:
258 ChildSpecs = [child_spec()]
260 Result = ok | {error, Error :: term()}
261 Takes a list of child specification as argument and returns ok
263 if all of them are syntactically correct, otherwise
264 {error,Error}.
265 count_children(SupRef) -> PropListOfCounts
267 Types:
269 SupRef = sup_ref()
271 PropListOfCounts = [Count]
272 Count =
273 {specs, ChildSpecCount :: integer() >= 0} |
274 {active, ActiveProcessCount :: integer() >= 0} |
275 {supervisors, ChildSupervisorCount :: integer() >= 0} |
276 {workers, ChildWorkerCount :: integer() >= 0}
277 Returns a property list (see proplists) containing the counts
279 for each of the following elements of the supervisor's child
280 specifications and managed processes:
281 * specs - The total count of children, dead or alive.
283 * active - The count of all actively running child processes
285 managed by this supervisor. For a simple_one_for_one super‐
286 visors, no check is done to ensure that each child process
287 is still alive, although the result provided here is likely
288 to be very accurate unless the supervisor is heavily over‐
289 loaded.
290 * supervisors - The count of all children marked as child_type
292 = supervisor in the specification list, regardless if the
293 child process is still alive.
294 * workers - The count of all children marked as child_type =
296 worker in the specification list, regardless if the child
297 process is still alive.
298 For a description of SupRef, see start_child/2.
300 delete_child(SupRef, Id) -> Result
302 Types:
304 SupRef = sup_ref()
306 Id = child_id()
307 Result = ok | {error, Error}
308 Error = running | restarting | not_found | simple_one_for_one
309 Tells supervisor SupRef to delete the child specification iden‐
311 tified by Id. The corresponding child process must not be run‐
312 ning. Use terminate_child/2 to terminate it.
313 For a description of SupRef, see start_child/2.
315 If successful, the function returns ok. If the child specifica‐
317 tion identified by Id exists but the corresponding child process
318 is running or is about to be restarted, the function returns
319 {error,running} or {error,restarting}, respectively. If the
320 child specification identified by Id does not exist, the func‐
321 tion returns {error,not_found}.
322 get_childspec(SupRef, Id) -> Result
324 Types:
326 SupRef = sup_ref()
328 Id = pid() | child_id()
329 Result = {ok, child_spec()} | {error, Error}
330 Error = not_found
331 Returns the child specification map for the child identified by
333 Id under supervisor SupRef. The returned map contains all keys,
334 both mandatory and optional.
335 For a description of SupRef, see start_child/2.
337 restart_child(SupRef, Id) -> Result
339 Types:
341 SupRef = sup_ref()
343 Id = child_id()
344 Result =
345 {ok, Child :: child()} |
346 {ok, Child :: child(), Info :: term()} |
347 {error, Error}
348 Error =
349 running | restarting | not_found | simple_one_for_one |
350 term()
351 Tells supervisor SupRef to restart a child process corresponding
353 to the child specification identified by Id. The child specifi‐
354 cation must exist, and the corresponding child process must not
355 be running.
356 Notice that for temporary children, the child specification is
358 automatically deleted when the child terminates; thus, it is not
359 possible to restart such children.
360 For a description of SupRef, see start_child/2.
362 If the child specification identified by Id does not exist, the
364 function returns {error,not_found}. If the child specification
365 exists but the corresponding process is already running, the
366 function returns {error,running}.
367 If the child process start function returns {ok,Child} or
369 {ok,Child,Info}, the pid is added to the supervisor and the
370 function returns the same value.
371 If the child process start function returns ignore, the pid
373 remains set to undefined and the function returns {ok,unde‐
374 fined}.
375 If the child process start function returns an error tuple or an
377 erroneous value, or if it fails, the function returns
378 {error,Error}, where Error is a term containing information
379 about the error.
380 start_child(SupRef, ChildSpec) -> startchild_ret()
382 Types:
384 SupRef = sup_ref()
386 ChildSpec = child_spec() | (List :: [term()])
387 startchild_ret() =
388 {ok, Child :: child()} |
389 {ok, Child :: child(), Info :: term()} |
390 {error, startchild_err()}
391 startchild_err() =
392 already_present | {already_started, Child :: child()} | term()
393 Dynamically adds a child specification to supervisor SupRef,
395 which starts the corresponding child process.
396 SupRef can be any of the following:
398 * The pid
400 * Name, if the supervisor is locally registered
402 * {Name,Node}, if the supervisor is locally registered at
404 another node
405 * {global,Name}, if the supervisor is globally registered
407 * {via,Module,Name}, if the supervisor is registered through
409 an alternative process registry
410 ChildSpec must be a valid child specification (unless the super‐
412 visor is a simple_one_for_one supervisor; see below). The child
413 process is started by using the start function as defined in the
414 child specification.
415 For a simple_one_for_one supervisor, the child specification
417 defined in Module:init/1 is used, and ChildSpec must instead be
418 an arbitrary list of terms List. The child process is then
419 started by appending List to the existing start function argu‐
420 ments, that is, by calling apply(M, F, A++List), where {M,F,A}
421 is the start function defined in the child specification.
422 * If there already exists a child specification with the spec‐
424 ified identifier, ChildSpec is discarded, and the function
425 returns {error,already_present} or
426 {error,{already_started,Child}}, depending on if the corre‐
427 sponding child process is running or not.
428 * If the child process start function returns {ok,Child} or
430 {ok,Child,Info}, the child specification and pid are added
431 to the supervisor and the function returns the same value.
432 * If the child process start function returns ignore, the
434 child specification is added to the supervisor (unless the
435 supervisor is a simple_one_for_one supervisor, see below),
436 the pid is set to undefined, and the function returns
437 {ok,undefined}.
438 For a simple_one_for_one supervisor, when a child process start
440 function returns ignore, the functions returns {ok,undefined}
441 and no child is added to the supervisor.
442 If the child process start function returns an error tuple or an
444 erroneous value, or if it fails, the child specification is dis‐
445 carded, and the function returns {error,Error}, where Error is a
446 term containing information about the error and child specifica‐
447 tion.
448 start_link(Module, Args) -> startlink_ret()
450 start_link(SupName, Module, Args) -> startlink_ret()
452 Types:
454 SupName = sup_name()
456 Module = module()
457 Args = term()
458 startlink_ret() =
459 {ok, pid()} | ignore | {error, startlink_err()}
460 startlink_err() =
461 {already_started, pid()} | {shutdown, term()} | term()
462 sup_name() =
463 {local, Name :: atom()} |
464 {global, Name :: atom()} |
465 {via, Module :: module(), Name :: any()}
466 Creates a supervisor process as part of a supervision tree. For
468 example, the function ensures that the supervisor is linked to
469 the calling process (its supervisor).
470 The created supervisor process calls Module:init/1 to find out
472 about restart strategy, maximum restart intensity, and child
473 processes. To ensure a synchronized startup procedure,
474 start_link/2,3 does not return until Module:init/1 has returned
475 and all child processes have been started.
476 * If SupName={local,Name}, the supervisor is registered
478 locally as Name using register/2.
479 * If SupName={global,Name}, the supervisor is registered glob‐
481 ally as Name using global:register_name/2.
482 * If SupName={via,Module,Name}, the supervisor is registered
484 as Name using the registry represented by Module. The Module
485 callback must export the functions register_name/2, unregis‐
486 ter_name/1, and send/2, which must behave like the corre‐
487 sponding functions in global. Thus, {via,global,Name} is a
488 valid reference.
489 If no name is provided, the supervisor is not registered.
491 Module is the name of the callback module.
493 Args is any term that is passed as the argument to Mod‐
495 ule:init/1.
496 * If the supervisor and its child processes are successfully
498 created (that is, if all child process start functions
499 return {ok,Child}, {ok,Child,Info}, or ignore), the function
500 returns {ok,Pid}, where Pid is the pid of the supervisor.
501 * If there already exists a process with the specified Sup‐
503 Name, the function returns {error,{already_started,Pid}},
504 where Pid is the pid of that process.
505 * If Module:init/1 returns ignore, this function returns
507 ignore as well, and the supervisor terminates with reason
508 normal.
509 * If Module:init/1 fails or returns an incorrect value, this
511 function returns {error,Term}, where Term is a term with
512 information about the error, and the supervisor terminates
513 with reason Term.
514 * If any child process start function fails or returns an
516 error tuple or an erroneous value, the supervisor first ter‐
517 minates all already started child processes with reason
518 shutdown and then terminate itself and returns {error,
519 {shutdown, Reason}}.
520 terminate_child(SupRef, Id) -> Result
522 Types:
524 SupRef = sup_ref()
526 Id = pid() | child_id()
527 Result = ok | {error, Error}
528 Error = not_found | simple_one_for_one
529 Tells supervisor SupRef to terminate the specified child.
531 If the supervisor is not simple_one_for_one, Id must be the
533 child specification identifier. The process, if any, is termi‐
534 nated and, unless it is a temporary child, the child specifica‐
535 tion is kept by the supervisor. The child process can later be
536 restarted by the supervisor. The child process can also be
537 restarted explicitly by calling restart_child/2. Use
538 delete_child/2 to remove the child specification.
539 If the child is temporary, the child specification is deleted as
541 soon as the process terminates. This means that delete_child/2
542 has no meaning and restart_child/2 cannot be used for these
543 children.
544 If the supervisor is simple_one_for_one, Id must be the pid() of
546 the child process. If the specified process is alive, but is not
547 a child of the specified supervisor, the function returns
548 {error,not_found}. If the child specification identifier is
549 specified instead of a pid(), the function returns {error,sim‐
550 ple_one_for_one}.
551 If successful, the function returns ok. If there is no child
553 specification with the specified Id, the function returns
554 {error,not_found}.
555 For a description of SupRef, see start_child/2.
557 which_children(SupRef) -> [{Id, Child, Type, Modules}]
559 Types:
561 SupRef = sup_ref()
563 Id = child_id() | undefined
564 Child = child() | restarting
565 Type = worker()
566 Modules = modules()
567 Returns a newly created list with information about all child
569 specifications and child processes belonging to supervisor
570 SupRef.
571 Notice that calling this function when supervising many chil‐
573 drens under low memory conditions can cause an out of memory
574 exception.
575 For a description of SupRef, see start_child/2.
577 The following information is given for each child specifica‐
579 tion/process:
580 * Id - As defined in the child specification or undefined for
582 a simple_one_for_one supervisor.
583 * Child - The pid of the corresponding child process, the atom
585 restarting if the process is about to be restarted, or unde‐
586 fined if there is no such process.
587 * Type - As defined in the child specification.
589 * Modules - As defined in the child specification.
591
593 The following function must be exported from a supervisor callback mod‐
594 ule.
595
597 Module:init(Args) -> Result
598 Types:
600 Args = term()
602 Result = {ok,{SupFlags,[ChildSpec]}} | ignore
603 SupFlags = sup_flags()
604 ChildSpec = child_spec()
605 Whenever a supervisor is started using start_link/2,3, this
607 function is called by the new process to find out about restart
608 strategy, maximum restart intensity, and child specifications.
609 Args is the Args argument provided to the start function.
611 SupFlags is the supervisor flags defining the restart strategy
613 and maximum restart intensity for the supervisor. [ChildSpec] is
614 a list of valid child specifications defining which child pro‐
615 cesses the supervisor must start and monitor. See the discussion
616 in section Supervision Principles earlier.
617 Notice that when the restart strategy is simple_one_for_one, the
619 list of child specifications must be a list with one child spec‐
620 ification only. (The child specification identifier is ignored.)
621 No child process is then started during the initialization
622 phase, but all children are assumed to be started dynamically
623 using start_child/2.
624 The function can also return ignore.
626 Notice that this function can also be called as a part of a code
628 upgrade procedure. Therefore, the function is not to have any
629 side effects. For more information about code upgrade of super‐
630 visors, see section Changing a Supervisor in OTP Design Princi‐
631 ples.
632
634 gen_event(3), gen_statem(3), gen_server(3), sys(3)
635Ericsson AB stdlib 3.4.5.1 supervisor(3)