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 be‐
13 haviors. A supervisor implemented using this module has a standard set
14 of interface functions and include functionality for tracing and error
15 reporting. Supervisors are used to build a hierarchical process struc‐
16 ture called a supervision tree, a nice way to structure a fault-toler‐
17 ant application. For more information, see Supervisor Behaviour in OTP
18 Design Principles.
19 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 de‐
82 fined using two integer values specified with keys intensity and period
83 in the above map. Assuming the values MaxR for intensity and MaxT for
84 period, then, if more than MaxR restarts occur within MaxT seconds, the
85 supervisor terminates all child processes and then itself. The termina‐
86 tion reason for the supervisor itself in that case will be shutdown.
87 intensity defaults to 1 and period defaults to 5.
88 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 ap‐
113 ply(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 su‐
118 pervisor.
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 tu‐
126 ple {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 in‐
228 ternally in supervisor. If the restart type of the child is tem‐
229 porary, the process is never to be restarted and therefore there
230 is no need to store the real argument list. Value undefined is
231 then stored instead.
232 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 {error,Er‐
286 ror}.
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 re‐
395 mains set to undefined and the function returns {ok,undefined}.
396 If the child process start function returns an error tuple or an
398 erroneous value, or if it fails, the function returns {error,Er‐
399 ror}, where Error is a term containing information about the er‐
400 ror.
401 start_child(SupRef, ChildSpec) -> startchild_ret()
403 Types:
405 SupRef = sup_ref()
407 ChildSpec = child_spec() | (List :: [term()])
408 startchild_ret() =
409 {ok, Child :: child()} |
410 {ok, Child :: child(), Info :: term()} |
411 {error, startchild_err()}
412 startchild_err() =
413 already_present | {already_started, Child :: child()} | term()
414 Dynamically adds a child specification to supervisor SupRef,
416 which starts the corresponding child process.
417 SupRef can be any of the following:
419 * The pid
421 * Name, if the supervisor is locally registered
423 * {Name,Node}, if the supervisor is locally registered at an‐
425 other node
426 * {global,Name}, if the supervisor is globally registered
428 * {via,Module,Name}, if the supervisor is registered through
430 an alternative process registry
431 ChildSpec must be a valid child specification (unless the super‐
433 visor is a simple_one_for_one supervisor; see below). The child
434 process is started by using the start function as defined in the
435 child specification.
436 For a simple_one_for_one supervisor, the child specification de‐
438 fined in Module:init/1 is used, and ChildSpec must instead be an
439 arbitrary list of terms List. The child process is then started
440 by appending List to the existing start function arguments, that
441 is, by calling apply(M, F, A++List), where {M,F,A} is the start
442 function defined in the child specification.
443 * If there already exists a child specification with the spec‐
445 ified identifier, ChildSpec is discarded, and the function
446 returns {error,already_present} or {error,{al‐
447 ready_started,Child}}, depending on if the corresponding
448 child process is running or not.
449 * If the child process start function returns {ok,Child} or
451 {ok,Child,Info}, the child specification and pid are added
452 to the supervisor and the function returns the same value.
453 * If the child process start function returns ignore, the
455 child specification is added to the supervisor (unless the
456 supervisor is a simple_one_for_one supervisor, see below),
457 the pid is set to undefined, and the function returns
458 {ok,undefined}.
459 For a simple_one_for_one supervisor, when a child process start
461 function returns ignore, the functions returns {ok,undefined}
462 and no child is added to the supervisor.
463 If the child process start function returns an error tuple or an
465 erroneous value, or if it fails, the child specification is dis‐
466 carded, and the function returns {error,Error}, where Error is a
467 term containing information about the error and child specifica‐
468 tion.
469 start_link(Module, Args) -> startlink_ret()
471 start_link(SupName, Module, Args) -> startlink_ret()
473 Types:
475 SupName = sup_name()
477 Module = module()
478 Args = term()
479 startlink_ret() =
480 {ok, pid()} | ignore | {error, startlink_err()}
481 startlink_err() =
482 {already_started, pid()} | {shutdown, term()} | term()
483 sup_name() =
484 {local, Name :: atom()} |
485 {global, Name :: atom()} |
486 {via, Module :: module(), Name :: any()}
487 Creates a supervisor process as part of a supervision tree. For
489 example, the function ensures that the supervisor is linked to
490 the calling process (its supervisor).
491 The created supervisor process calls Module:init/1 to find out
493 about restart strategy, maximum restart intensity, and child
494 processes. To ensure a synchronized startup procedure,
495 start_link/2,3 does not return until Module:init/1 has returned
496 and all child processes have been started.
497 * If SupName={local,Name}, the supervisor is registered lo‐
499 cally as Name using register/2.
500 * If SupName={global,Name}, the supervisor is registered glob‐
502 ally as Name using global:register_name/2.
503 * If SupName={via,Module,Name}, the supervisor is registered
505 as Name using the registry represented by Module. The Module
506 callback must export the functions register_name/2, unregis‐
507 ter_name/1, and send/2, which must behave like the corre‐
508 sponding functions in global. Thus, {via,global,Name} is a
509 valid reference.
510 If no name is provided, the supervisor is not registered.
512 Module is the name of the callback module.
514 Args is any term that is passed as the argument to Mod‐
516 ule:init/1.
517 * If the supervisor and its child processes are successfully
519 created (that is, if all child process start functions re‐
520 turn {ok,Child}, {ok,Child,Info}, or ignore), the function
521 returns {ok,Pid}, where Pid is the pid of the supervisor.
522 * If there already exists a process with the specified Sup‐
524 Name, the function returns {error,{already_started,Pid}},
525 where Pid is the pid of that process.
526 * If Module:init/1 returns ignore, this function returns ig‐
528 nore as well, and the supervisor terminates with reason nor‐
529 mal.
530 * If Module:init/1 fails or returns an incorrect value, this
532 function returns {error,Term}, where Term is a term with in‐
533 formation about the error, and the supervisor terminates
534 with reason Term.
535 * If any child process start function fails or returns an er‐
537 ror tuple or an erroneous value, the supervisor first termi‐
538 nates all already started child processes with reason shut‐
539 down and then terminate itself and returns {error, {shut‐
540 down, Reason}}.
541 terminate_child(SupRef, Id) -> Result
543 Types:
545 SupRef = sup_ref()
547 Id = pid() | child_id()
548 Result = ok | {error, Error}
549 Error = not_found | simple_one_for_one
550 Tells supervisor SupRef to terminate the specified child.
552 If the supervisor is not simple_one_for_one, Id must be the
554 child specification identifier. The process, if any, is termi‐
555 nated and, unless it is a temporary child, the child specifica‐
556 tion is kept by the supervisor. The child process can later be
557 restarted by the supervisor. The child process can also be
558 restarted explicitly by calling restart_child/2. Use
559 delete_child/2 to remove the child specification.
560 If the child is temporary, the child specification is deleted as
562 soon as the process terminates. This means that delete_child/2
563 has no meaning and restart_child/2 cannot be used for these
564 children.
565 If the supervisor is simple_one_for_one, Id must be the pid() of
567 the child process. If the specified process is alive, but is not
568 a child of the specified supervisor, the function returns {er‐
569 ror,not_found}. If the child specification identifier is speci‐
570 fied instead of a pid(), the function returns {error,sim‐
571 ple_one_for_one}.
572 If successful, the function returns ok. If there is no child
574 specification with the specified Id, the function returns {er‐
575 ror,not_found}.
576 For a description of SupRef, see start_child/2.
578 which_children(SupRef) -> [{Id, Child, Type, Modules}]
580 Types:
582 SupRef = sup_ref()
584 Id = child_id() | undefined
585 Child = child() | restarting
586 Type = worker()
587 Modules = modules()
588 Returns a newly created list with information about all child
590 specifications and child processes belonging to supervisor
591 SupRef.
592 Notice that calling this function when supervising many children
594 under low memory conditions can cause an out of memory excep‐
595 tion.
596 For a description of SupRef, see start_child/2.
598 The following information is given for each child specifica‐
600 tion/process:
601 * Id - As defined in the child specification or undefined for
603 a simple_one_for_one supervisor.
604 * Child - The pid of the corresponding child process, the atom
606 restarting if the process is about to be restarted, or unde‐
607 fined if there is no such process.
608 * Type - As defined in the child specification.
610 * Modules - As defined in the child specification.
612
614 The following function must be exported from a supervisor callback mod‐
615 ule.
616
618 Module:init(Args) -> Result
619 Types:
621 Args = term()
623 Result = {ok,{SupFlags,[ChildSpec]}} | ignore
624 SupFlags = sup_flags()
625 ChildSpec = child_spec()
626 Whenever a supervisor is started using start_link/2,3, this
628 function is called by the new process to find out about restart
629 strategy, maximum restart intensity, and child specifications.
630 Args is the Args argument provided to the start function.
632 SupFlags is the supervisor flags defining the restart strategy
634 and maximum restart intensity for the supervisor. [ChildSpec] is
635 a list of valid child specifications defining which child pro‐
636 cesses the supervisor must start and monitor. See the discussion
637 in section Supervision Principles earlier.
638 Notice that when the restart strategy is simple_one_for_one, the
640 list of child specifications must be a list with one child spec‐
641 ification only. (The child specification identifier is ignored.)
642 No child process is then started during the initialization
643 phase, but all children are assumed to be started dynamically
644 using start_child/2.
645 The function can also return ignore.
647 Notice that this function can also be called as a part of a code
649 upgrade procedure. Therefore, the function is not to have any
650 side effects. For more information about code upgrade of super‐
651 visors, see section Changing a Supervisor in OTP Design Princi‐
652 ples.
653
655 gen_event(3), gen_statem(3), gen_server(3), sys(3)
656Ericsson AB stdlib 3.14.2.1 supervisor(3)