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 strategy() =
240 one_for_all | one_for_one | rest_for_one | simple_one_for_one
241 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 The tuple format is kept for backward compatibility only. A map
251 is preferred; see more details above.
252 sup_ref() =
254 (Name :: atom()) |
255 {Name :: atom(), Node :: node()} |
256 {global, Name :: atom()} |
257 {via, Module :: module(), Name :: any()} |
258 pid()
259 worker() = worker | supervisor
261
263 check_childspecs(ChildSpecs) -> Result
264 Types:
266 ChildSpecs = [child_spec()]
268 Result = ok | {error, Error :: term()}
269 Takes a list of child specification as argument and returns ok
271 if all of them are syntactically correct, otherwise
272 {error,Error}.
273 count_children(SupRef) -> PropListOfCounts
275 Types:
277 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 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 * specs - The total count of children, dead or alive.
291 * 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 * 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 * 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 For a description of SupRef, see start_child/2.
308 delete_child(SupRef, Id) -> Result
310 Types:
312 SupRef = sup_ref()
314 Id = child_id()
315 Result = ok | {error, Error}
316 Error = running | restarting | not_found | simple_one_for_one
317 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 For a description of SupRef, see start_child/2.
323 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 get_childspec(SupRef, Id) -> Result
332 Types:
334 SupRef = sup_ref()
336 Id = pid() | child_id()
337 Result = {ok, child_spec()} | {error, Error}
338 Error = not_found
339 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 For a description of SupRef, see start_child/2.
345 restart_child(SupRef, Id) -> Result
347 Types:
349 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 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 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 For a description of SupRef, see start_child/2.
370 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 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 If the child process start function returns ignore, the pid
381 remains set to undefined and the function returns {ok,unde‐
382 fined}.
383 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 start_child(SupRef, ChildSpec) -> startchild_ret()
390 Types:
392 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 Dynamically adds a child specification to supervisor SupRef,
403 which starts the corresponding child process.
404 SupRef can be any of the following:
406 * The pid
408 * Name, if the supervisor is locally registered
410 * {Name,Node}, if the supervisor is locally registered at
412 another node
413 * {global,Name}, if the supervisor is globally registered
415 * {via,Module,Name}, if the supervisor is registered through
417 an alternative process registry
418 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 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 * 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 * 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 * 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 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 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 start_link(Module, Args) -> startlink_ret()
458 start_link(SupName, Module, Args) -> startlink_ret()
460 Types:
462 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 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 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 * If SupName={local,Name}, the supervisor is registered
486 locally as Name using register/2.
487 * If SupName={global,Name}, the supervisor is registered glob‐
489 ally as Name using global:register_name/2.
490 * 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 If no name is provided, the supervisor is not registered.
499 Module is the name of the callback module.
501 Args is any term that is passed as the argument to Mod‐
503 ule:init/1.
504 * 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 * 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 * If Module:init/1 returns ignore, this function returns
515 ignore as well, and the supervisor terminates with reason
516 normal.
517 * 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 * 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 terminate_child(SupRef, Id) -> Result
530 Types:
532 SupRef = sup_ref()
534 Id = pid() | child_id()
535 Result = ok | {error, Error}
536 Error = not_found | simple_one_for_one
537 Tells supervisor SupRef to terminate the specified child.
539 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 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 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 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 For a description of SupRef, see start_child/2.
565 which_children(SupRef) -> [{Id, Child, Type, Modules}]
567 Types:
569 SupRef = sup_ref()
571 Id = child_id() | undefined
572 Child = child() | restarting
573 Type = worker()
574 Modules = modules()
575 Returns a newly created list with information about all child
577 specifications and child processes belonging to supervisor
578 SupRef.
579 Notice that calling this function when supervising many chil‐
581 drens under low memory conditions can cause an out of memory
582 exception.
583 For a description of SupRef, see start_child/2.
585 The following information is given for each child specifica‐
587 tion/process:
588 * Id - As defined in the child specification or undefined for
590 a simple_one_for_one supervisor.
591 * 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 * Type - As defined in the child specification.
597 * Modules - As defined in the child specification.
599
601 The following function must be exported from a supervisor callback mod‐
602 ule.
603
605 Module:init(Args) -> Result
606 Types:
608 Args = term()
610 Result = {ok,{SupFlags,[ChildSpec]}} | ignore
611 SupFlags = sup_flags()
612 ChildSpec = child_spec()
613 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 Args is the Args argument provided to the start function.
619 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 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 The function can also return ignore.
634 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
642 gen_event(3), gen_statem(3), gen_server(3), sys(3)
643Ericsson AB stdlib 3.12.1 supervisor(3)