.TH supervisor 3erl "stdlib 3.2" "Ericsson AB" "Erlang Module Definition"
.SH NAME
supervisor \- Generic supervisor behavior.
.SH DESCRIPTION
.LP
This behavior module provides a supervisor, a process that supervises other processes called child processes\&. A child process can either be another supervisor or a worker process\&. Worker processes are normally implemented using one of the \fB\fIgen_event\fR\&\fR\&, \fB\fIgen_fsm\fR\&\fR\&, \fB\fIgen_server\fR\&\fR\&, or \fB\fIgen_statem\fR\&\fR\& behaviors\&. A supervisor implemented using this module has a standard set of interface functions and include functionality for tracing and error reporting\&. Supervisors are used to build a hierarchical process structure called a supervision tree, a nice way to structure a fault-tolerant application\&. For more information, see \fB Supervisor Behaviour\fR\& in OTP Design Principles\&.
.LP
A supervisor expects the definition of which child processes to supervise to be specified in a callback module exporting a predefined set of functions\&.
.LP
Unless otherwise stated, all functions in this module fail if the specified supervisor does not exist or if bad arguments are specified\&.
.SH "SUPERVISION PRINCIPLES"

.LP
The supervisor is responsible for starting, stopping, and monitoring its child processes\&. The basic idea of a supervisor is that it must keep its child processes alive by restarting them when necessary\&.
.LP
The children of a supervisor are defined as a list of \fIchild specifications\fR\&\&. When the supervisor is started, the child processes are started in order from left to right according to this list\&. When the supervisor terminates, it first terminates its child processes in reversed start order, from right to left\&.
.LP
The supervisor properties are defined by the supervisor flags\&. The type definition for the supervisor flags is as follows:
.LP
.nf

sup_flags() = #{strategy => strategy(),         % optional
                intensity => non_neg_integer(), % optional
                period => pos_integer()}        % optional
.fi
.LP
A supervisor can have one of the following \fIrestart strategies\fR\& specified with the \fIstrategy\fR\& key in the above map:
.RS 2
.TP 2
*
\fIone_for_one\fR\& - If one child process terminates and is to be restarted, only that child process is affected\&. This is the default restart strategy\&.
.LP
.TP 2
*
\fIone_for_all\fR\& - If one child process terminates and is to be restarted, all other child processes are terminated and then all child processes are restarted\&.
.LP
.TP 2
*
\fIrest_for_one\fR\& - If one child process terminates and is to be restarted, the \&'rest\&' of the child processes (that is, the child processes after the terminated child process in the start order) are terminated\&. Then the terminated child process and all child processes after it are restarted\&.
.LP
.TP 2
*
\fIsimple_one_for_one\fR\& - A simplified \fIone_for_one\fR\& supervisor, where all child processes are dynamically added instances of the same process type, that is, running the same code\&.
.RS 2
.LP
Functions \fB\fIdelete_child/2\fR\&\fR\& and \fB\fIrestart_child/2\fR\&\fR\& are invalid for \fIsimple_one_for_one\fR\& supervisors and return \fI{error,simple_one_for_one}\fR\& if the specified supervisor uses this restart strategy\&.
.RE

.RS 2
.LP
Function \fB\fIterminate_child/2\fR\&\fR\& can be used for children under \fIsimple_one_for_one\fR\& supervisors by specifying the child\&'s \fIpid()\fR\& as the second argument\&. If instead the child specification identifier is used, \fIterminate_child/2\fR\& return \fI{error,simple_one_for_one}\fR\&\&.
.RE

.RS 2
.LP
As a \fIsimple_one_for_one\fR\& supervisor can have many children, it shuts them all down asynchronously\&. This means that the children do their cleanup in parallel, and therefore the order in which they are stopped is not defined\&.
.RE

.LP
.RE

.LP
To prevent a supervisor from getting into an infinite loop of child process terminations and restarts, a \fImaximum restart intensity\fR\& is defined using two integer values specified with keys \fIintensity\fR\& and \fIperiod\fR\& in the above map\&. Assuming the values \fIMaxR\fR\& for \fIintensity\fR\& and \fIMaxT\fR\& for \fIperiod\fR\&, then, if more than \fIMaxR\fR\& restarts occur within \fIMaxT\fR\& seconds, the supervisor terminates all child processes and then itself\&. \fIintensity\fR\& defaults to \fI1\fR\& and \fIperiod\fR\& defaults to \fI5\fR\&\&.
.LP
The type definition of a child specification is as follows:
.LP
.nf

child_spec() = #{id => child_id(),       % mandatory
                 start => mfargs(),      % mandatory
                 restart => restart(),   % optional
                 shutdown => shutdown(), % optional
                 type => worker(),       % optional
                 modules => modules()}   % optional
.fi
.LP
The old tuple format is kept for backwards compatibility, see \fBchild_spec()\fR\&, but the map is preferred\&.
.RS 2
.TP 2
*
\fIid\fR\& is used to identify the child specification internally by the supervisor\&.
.RS 2
.LP
The \fIid\fR\& key is mandatory\&.
.RE

.RS 2
.LP
Notice that this identifier on occations has been called "name"\&. As far as possible, the terms "identifier" or "id" are now used but to keep backward compatibility, some occurences of "name" can still be found, for example in error messages\&.
.RE

.LP
.TP 2
*
\fIstart\fR\& defines the function call used to start the child process\&. It must be a module-function-arguments tuple \fI{M,F,A}\fR\& used as \fIapply(M,F,A)\fR\&\&.
.RS 2
.LP
The start function \fImust create and link to\fR\& the child process, and must return \fI{ok,Child}\fR\& or \fI{ok,Child,Info}\fR\&, where \fIChild\fR\& is the pid of the child process and \fIInfo\fR\& any term that is ignored by the supervisor\&.
.RE

.RS 2
.LP
The start function can also return \fIignore\fR\& if the child process for some reason cannot be started, in which case the child specification is kept by the supervisor (unless it is a temporary child) but the non-existing child process is ignored\&.
.RE

.RS 2
.LP
If something goes wrong, the function can also return an error tuple \fI{error,Error}\fR\&\&.
.RE

.RS 2
.LP
Notice that the \fIstart_link\fR\& functions of the different behavior modules fulfill the above requirements\&.
.RE

.RS 2
.LP
The \fIstart\fR\& key is mandatory\&.
.RE

.LP
.TP 2
*
\fIrestart\fR\& defines when a terminated child process must be restarted\&. A \fIpermanent\fR\& child process is always restarted\&. A \fItemporary\fR\& child process is never restarted (even when the supervisor\&'s restart strategy is \fIrest_for_one\fR\& or \fIone_for_all\fR\& and a sibling\&'s death causes the temporary process to be terminated)\&. A \fItransient\fR\& child process is restarted only if it terminates abnormally, that is, with another exit reason than \fInormal\fR\&, \fIshutdown\fR\&, or \fI{shutdown,Term}\fR\&\&.
.RS 2
.LP
The \fIrestart\fR\& key is optional\&. If it is not specified, it defaults to \fIpermanent\fR\&\&.
.RE

.LP
.TP 2
*
\fIshutdown\fR\& defines how a child process must be terminated\&. \fIbrutal_kill\fR\& means that the child process is unconditionally terminated using \fIexit(Child,kill)\fR\&\&. An integer time-out value means that the supervisor tells the child process to terminate by calling \fIexit(Child,shutdown)\fR\& and then wait for an exit signal with reason \fIshutdown\fR\& back from the child process\&. If no exit signal is received within the specified number of milliseconds, the child process is unconditionally terminated using \fIexit(Child,kill)\fR\&\&.
.RS 2
.LP
If the child process is another supervisor, the shutdown time is to be set to \fIinfinity\fR\& to give the subtree ample time to shut down\&. It is also allowed to set it to \fIinfinity\fR\&, if the child process is a worker\&.
.RE

.LP

.RS -4
.B
Warning:
.RE
Be careful when setting the shutdown time to \fIinfinity\fR\& when the child process is a worker\&. Because, in this situation, the termination of the supervision tree depends on the child process, it must be implemented in a safe way and its cleanup procedure must always return\&.

.RS 2
.LP
Notice that all child processes implemented using the standard OTP behavior modules automatically adhere to the shutdown protocol\&.
.RE

.RS 2
.LP
The \fIshutdown\fR\& key is optional\&. If it is not specified, it defaults to \fI5000\fR\& if the child is of type \fIworker\fR\& and it defaults to \fIinfinity\fR\& if the child is of type \fIsupervisor\fR\&\&.
.RE

.LP
.TP 2
*
\fItype\fR\& specifies if the child process is a supervisor or a worker\&.
.RS 2
.LP
The \fItype\fR\& key is optional\&. If it is not specified, it defaults to \fIworker\fR\&\&.
.RE

.LP
.TP 2
*
\fImodules\fR\& is used by the release handler during code replacement to determine which processes are using a certain module\&. As a rule of thumb, if the child process is a \fIsupervisor\fR\&, \fIgen_server\fR\&, \fIgen_statem\fR\&, or \fIgen_fsm\fR\&, this is to be a list with one element \fI[Module]\fR\&, where \fIModule\fR\& is the callback module\&. If the child process is an event manager (\fIgen_event\fR\&) with a dynamic set of callback modules, value \fIdynamic\fR\& must be used\&. For more information about release handling, see \fB Release Handling\fR\& in OTP Design Principles\&.
.RS 2
.LP
The \fImodules\fR\& key is optional\&. If it is not specified, it defaults to \fI[M]\fR\&, where \fIM\fR\& comes from the child\&'s start \fI{M,F,A}\fR\&\&.
.RE

.LP
.TP 2
*
Internally, the supervisor also keeps track of the pid \fIChild\fR\& of the child process, or \fIundefined\fR\& if no pid exists\&.
.LP
.RE

.SH DATA TYPES
.nf

\fBchild()\fR\& = undefined | pid()
.br
.fi
.nf

\fBchild_id()\fR\& = term()
.br
.fi
.RS
.LP
Not a \fIpid()\fR\&\&.
.RE

.nf

\fBchild_spec()\fR\& = 
.br
    #{id := \fBchild_id()\fR\&,
.br
      start := \fBmfargs()\fR\&,
.br
      restart => \fBrestart()\fR\&,
.br
      shutdown => \fBshutdown()\fR\&,
.br
      type => \fBworker()\fR\&,
.br
      modules => \fBmodules()\fR\&} |
.br
    {Id :: \fBchild_id()\fR\&,
.br
     StartFunc :: \fBmfargs()\fR\&,
.br
     Restart :: \fBrestart()\fR\&,
.br
     Shutdown :: \fBshutdown()\fR\&,
.br
     Type :: \fBworker()\fR\&,
.br
     Modules :: \fBmodules()\fR\&}
.br
.fi
.RS
.LP
The tuple format is kept for backward compatibility only\&. A map is preferred; see more details \fBabove\fR\&\&.
.RE

.nf

\fBmfargs()\fR\& = 
.br
    {M :: module(), F :: atom(), A :: [term()] | undefined}
.br
.fi
.RS
.LP
Value \fIundefined\fR\& for \fIA\fR\& (the argument list) is only to be used internally in \fIsupervisor\fR\&\&. If the restart type of the child is \fItemporary\fR\&, the process is never to be restarted and therefore there is no need to store the real argument list\&. Value \fIundefined\fR\& is then stored instead\&.
.RE

.nf

\fBmodules()\fR\& = [module()] | dynamic
.br
.fi
.nf

\fBrestart()\fR\& = permanent | transient | temporary
.br
.fi
.nf

\fBshutdown()\fR\& = brutal_kill | timeout()
.br
.fi
.nf

\fBstrategy()\fR\& = 
.br
    one_for_all | one_for_one | rest_for_one | simple_one_for_one
.br
.fi
.nf

\fBsup_flags()\fR\& = 
.br
    #{strategy => \fBstrategy()\fR\&,
.br
      intensity => integer() >= 0,
.br
      period => integer() >= 1} |
.br
    {RestartStrategy :: \fBstrategy()\fR\&,
.br
     Intensity :: integer() >= 0,
.br
     Period :: integer() >= 1}
.br
.fi
.RS
.LP
The tuple format is kept for backward compatibility only\&. A map is preferred; see more details \fBabove\fR\&\&.
.RE

.nf

\fBsup_ref()\fR\& = 
.br
    (Name :: atom()) |
.br
    {Name :: atom(), Node :: node()} |
.br
    {global, Name :: atom()} |
.br
    {via, Module :: module(), Name :: any()} |
.br
    pid()
.br
.fi
.nf

\fBworker()\fR\& = worker | supervisor
.br
.fi
.SH EXPORTS
.LP
.nf

.B
check_childspecs(ChildSpecs) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
ChildSpecs = [\fBchild_spec()\fR\&]
.br
Result = ok | {error, Error :: term()}
.br
.RE
.RE
.RS
.LP
Takes a list of child specification as argument and returns \fIok\fR\& if all of them are syntactically correct, otherwise \fI{error,Error}\fR\&\&.
.RE

.LP
.nf

.B
count_children(SupRef) -> PropListOfCounts
.br
.fi
.br
.RS
.LP
Types:

.RS 3
SupRef = \fBsup_ref()\fR\&
.br
PropListOfCounts = [Count]
.br
Count = 
.br
    {specs, ChildSpecCount :: integer() >= 0} |
.br
    {active, ActiveProcessCount :: integer() >= 0} |
.br
    {supervisors, ChildSupervisorCount :: integer() >= 0} |
.br
    {workers, ChildWorkerCount :: integer() >= 0}
.br
.RE
.RE
.RS
.LP
Returns a property list (see \fB\fIproplists\fR\&\fR\&) containing the counts for each of the following elements of the supervisor\&'s child specifications and managed processes:
.RS 2
.TP 2
*
\fIspecs\fR\& - The total count of children, dead or alive\&.
.LP
.TP 2
*
\fIactive\fR\& - The count of all actively running child processes managed by this supervisor\&. For a \fIsimple_one_for_one\fR\& supervisors, no check is done to ensure that each child process is still alive, although the result provided here is likely to be very accurate unless the supervisor is heavily overloaded\&.
.LP
.TP 2
*
\fIsupervisors\fR\& - The count of all children marked as \fIchild_type = supervisor\fR\& in the specification list, regardless if the child process is still alive\&.
.LP
.TP 2
*
\fIworkers\fR\& - The count of all children marked as \fIchild_type = worker\fR\& in the specification list, regardless if the child process is still alive\&.
.LP
.RE

.LP
For a description of \fISupRef\fR\&, see \fB\fIstart_child/2\fR\&\fR\&\&.
.RE

.LP
.nf

.B
delete_child(SupRef, Id) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
SupRef = \fBsup_ref()\fR\&
.br
Id = \fBchild_id()\fR\&
.br
Result = ok | {error, Error}
.br
Error = running | restarting | not_found | simple_one_for_one
.br
.RE
.RE
.RS
.LP
Tells supervisor \fISupRef\fR\& to delete the child specification identified by \fIId\fR\&\&. The corresponding child process must not be running\&. Use \fB\fIterminate_child/2\fR\&\fR\& to terminate it\&.
.LP
For a description of \fISupRef\fR\&, see \fB\fIstart_child/2\fR\&\fR\&\&.
.LP
If successful, the function returns \fIok\fR\&\&. If the child specification identified by \fIId\fR\& exists but the corresponding child process is running or is about to be restarted, the function returns \fI{error,running}\fR\& or \fI{error,restarting}\fR\&, respectively\&. If the child specification identified by \fIId\fR\& does not exist, the function returns \fI{error,not_found}\fR\&\&.
.RE

.LP
.nf

.B
get_childspec(SupRef, Id) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
SupRef = \fBsup_ref()\fR\&
.br
Id = pid() | \fBchild_id()\fR\&
.br
Result = {ok, \fBchild_spec()\fR\&} | {error, Error}
.br
Error = not_found
.br
.RE
.RE
.RS
.LP
Returns the child specification map for the child identified by \fIId\fR\& under supervisor \fISupRef\fR\&\&. The returned map contains all keys, both mandatory and optional\&.
.LP
For a description of \fISupRef\fR\&, see \fB\fIstart_child/2\fR\&\fR\&\&.
.RE

.LP
.nf

.B
restart_child(SupRef, Id) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
SupRef = \fBsup_ref()\fR\&
.br
Id = \fBchild_id()\fR\&
.br
Result = 
.br
    {ok, Child :: \fBchild()\fR\&} |
.br
    {ok, Child :: \fBchild()\fR\&, Info :: term()} |
.br
    {error, Error}
.br
Error = 
.br
    running | restarting | not_found | simple_one_for_one | term()
.br
.RE
.RE
.RS
.LP
Tells supervisor \fISupRef\fR\& to restart a child process corresponding to the child specification identified by \fIId\fR\&\&. The child specification must exist, and the corresponding child process must not be running\&.
.LP
Notice that for temporary children, the child specification is automatically deleted when the child terminates; thus, it is not possible to restart such children\&.
.LP
For a description of \fISupRef\fR\&, see \fB\fIstart_child/2\fR\&\fR\&\&.
.LP
If the child specification identified by \fIId\fR\& does not exist, the function returns \fI{error,not_found}\fR\&\&. If the child specification exists but the corresponding process is already running, the function returns \fI{error,running}\fR\&\&.
.LP
If the child process start function returns \fI{ok,Child}\fR\& or \fI{ok,Child,Info}\fR\&, the pid is added to the supervisor and the function returns the same value\&.
.LP
If the child process start function returns \fIignore\fR\&, the pid remains set to \fIundefined\fR\& and the function returns \fI{ok,undefined}\fR\&\&.
.LP
If the child process start function returns an error tuple or an erroneous value, or if it fails, the function returns \fI{error,Error}\fR\&, where \fIError\fR\& is a term containing information about the error\&.
.RE

.LP
.nf

.B
start_child(SupRef, ChildSpec) -> startchild_ret()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
SupRef = \fBsup_ref()\fR\&
.br
ChildSpec = \fBchild_spec()\fR\& | (List :: [term()])
.br
.nf
\fBstartchild_ret()\fR\& = 
.br
    {ok, Child :: \fBchild()\fR\&} |
.br
    {ok, Child :: \fBchild()\fR\&, Info :: term()} |
.br
    {error, \fBstartchild_err()\fR\&}
.fi
.br
.nf
\fBstartchild_err()\fR\& = 
.br
    already_present | {already_started, Child :: \fBchild()\fR\&} | term()
.fi
.br
.RE
.RE
.RS
.LP
Dynamically adds a child specification to supervisor \fISupRef\fR\&, which starts the corresponding child process\&.
.LP
\fISupRef\fR\& can be any of the following:
.RS 2
.TP 2
*
The pid
.LP
.TP 2
*
\fIName\fR\&, if the supervisor is locally registered
.LP
.TP 2
*
\fI{Name,Node}\fR\&, if the supervisor is locally registered at another node
.LP
.TP 2
*
\fI{global,Name}\fR\&, if the supervisor is globally registered
.LP
.TP 2
*
\fI{via,Module,Name}\fR\&, if the supervisor is registered through an alternative process registry
.LP
.RE

.LP
\fIChildSpec\fR\& must be a valid child specification (unless the supervisor is a \fIsimple_one_for_one\fR\& supervisor; see below)\&. The child process is started by using the start function as defined in the child specification\&.
.LP
For a \fIsimple_one_for_one\fR\& supervisor, the child specification defined in \fIModule:init/1\fR\& is used, and \fIChildSpec\fR\& must instead be an arbitrary list of terms \fIList\fR\&\&. The child process is then started by appending \fIList\fR\& to the existing start function arguments, that is, by calling \fIapply(M, F, A++List)\fR\&, where \fI{M,F,A}\fR\& is the start function defined in the child specification\&.
.RS 2
.TP 2
*
If there already exists a child specification with the specified identifier, \fIChildSpec\fR\& is discarded, and the function returns \fI{error,already_present}\fR\& or \fI{error,{already_started,Child}}\fR\&, depending on if the corresponding child process is running or not\&.
.LP
.TP 2
*
If the child process start function returns \fI{ok,Child}\fR\& or \fI{ok,Child,Info}\fR\&, the child specification and pid are added to the supervisor and the function returns the same value\&.
.LP
.TP 2
*
If the child process start function returns \fIignore\fR\&, the child specification is added to the supervisor (unless the supervisor is a \fIsimple_one_for_one\fR\& supervisor, see below), the pid is set to \fIundefined\fR\&, and the function returns \fI{ok,undefined}\fR\&\&.
.LP
.RE

.LP
For a \fIsimple_one_for_one\fR\& supervisor, when a child process start function returns \fIignore\fR\&, the functions returns \fI{ok,undefined}\fR\& and no child is added to the supervisor\&.
.LP
If the child process start function returns an error tuple or an erroneous value, or if it fails, the child specification is discarded, and the function returns \fI{error,Error}\fR\&, where \fIError\fR\& is a term containing information about the error and child specification\&.
.RE

.LP
.nf

.B
start_link(Module, Args) -> startlink_ret()
.br
.fi
.br
.nf

.B
start_link(SupName, Module, Args) -> startlink_ret()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
SupName = \fBsup_name()\fR\&
.br
Module = module()
.br
Args = term()
.br
.nf
\fBstartlink_ret()\fR\& = 
.br
    {ok, pid()} | ignore | {error, \fBstartlink_err()\fR\&}
.fi
.br
.nf
\fBstartlink_err()\fR\& = 
.br
    {already_started, pid()} | {shutdown, term()} | term()
.fi
.br
.nf
\fBsup_name()\fR\& = 
.br
    {local, Name :: atom()} |
.br
    {global, Name :: atom()} |
.br
    {via, Module :: module(), Name :: any()}
.fi
.br
.RE
.RE
.RS
.LP
Creates a supervisor process as part of a supervision tree\&. For example, the function ensures that the supervisor is linked to the calling process (its supervisor)\&.
.LP
The created supervisor process calls \fIModule:init/1\fR\& to find out about restart strategy, maximum restart intensity, and child processes\&. To ensure a synchronized startup procedure, \fIstart_link/2,3\fR\& does not return until \fIModule:init/1\fR\& has returned and all child processes have been started\&.
.RS 2
.TP 2
*
If \fISupName={local,Name}\fR\&, the supervisor is registered locally as \fIName\fR\& using \fIregister/2\fR\&\&.
.LP
.TP 2
*
If \fISupName={global,Name}\fR\&, the supervisor is registered globally as \fIName\fR\& using \fB\fIglobal:register_name/2\fR\&\fR\&\&.
.LP
.TP 2
*
If \fISupName={via,Module,Name}\fR\&, the supervisor is registered as \fIName\fR\& using the registry represented by \fIModule\fR\&\&. The \fIModule\fR\& callback must export the functions \fIregister_name/2\fR\&, \fIunregister_name/1\fR\&, and \fIsend/2\fR\&, which must behave like the corresponding functions in \fB\fIglobal\fR\&\fR\&\&. Thus, \fI{via,global,Name}\fR\& is a valid reference\&.
.LP
.RE

.LP
If no name is provided, the supervisor is not registered\&.
.LP
\fIModule\fR\& is the name of the callback module\&.
.LP
\fIArgs\fR\& is any term that is passed as the argument to \fIModule:init/1\fR\&\&.
.RS 2
.TP 2
*
If the supervisor and its child processes are successfully created (that is, if all child process start functions return \fI{ok,Child}\fR\&, \fI{ok,Child,Info}\fR\&, or \fIignore\fR\&), the function returns \fI{ok,Pid}\fR\&, where \fIPid\fR\& is the pid of the supervisor\&.
.LP
.TP 2
*
If there already exists a process with the specified \fISupName\fR\&, the function returns \fI{error,{already_started,Pid}}\fR\&, where \fIPid\fR\& is the pid of that process\&.
.LP
.TP 2
*
If \fIModule:init/1\fR\& returns \fIignore\fR\&, this function returns \fIignore\fR\& as well, and the supervisor terminates with reason \fInormal\fR\&\&.
.LP
.TP 2
*
If \fIModule:init/1\fR\& fails or returns an incorrect value, this function returns \fI{error,Term}\fR\&, where \fITerm\fR\& is a term with information about the error, and the supervisor terminates with reason \fITerm\fR\&\&.
.LP
.TP 2
*
If any child process start function fails or returns an error tuple or an erroneous value, the supervisor first terminates all already started child processes with reason \fIshutdown\fR\& and then terminate itself and returns \fI{error, {shutdown, Reason}}\fR\&\&.
.LP
.RE

.RE

.LP
.nf

.B
terminate_child(SupRef, Id) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
SupRef = \fBsup_ref()\fR\&
.br
Id = pid() | \fBchild_id()\fR\&
.br
Result = ok | {error, Error}
.br
Error = not_found | simple_one_for_one
.br
.RE
.RE
.RS
.LP
Tells supervisor \fISupRef\fR\& to terminate the specified child\&.
.LP
If the supervisor is not \fIsimple_one_for_one\fR\&, \fIId\fR\& must be the child specification identifier\&. The process, if any, is terminated and, unless it is a temporary child, the child specification is kept by the supervisor\&. The child process can later be restarted by the supervisor\&. The child process can also be restarted explicitly by calling \fB\fIrestart_child/2\fR\&\fR\&\&. Use \fB\fIdelete_child/2\fR\&\fR\& to remove the child specification\&.
.LP
If the child is temporary, the child specification is deleted as soon as the process terminates\&. This means that \fIdelete_child/2\fR\& has no meaning and \fIrestart_child/2\fR\& cannot be used for these children\&.
.LP
If the supervisor is \fIsimple_one_for_one\fR\&, \fIId\fR\& must be the \fIpid()\fR\& of the child process\&. If the specified process is alive, but is not a child of the specified supervisor, the function returns \fI{error,not_found}\fR\&\&. If the child specification identifier is specified instead of a \fIpid()\fR\&, the function returns \fI{error,simple_one_for_one}\fR\&\&.
.LP
If successful, the function returns \fIok\fR\&\&. If there is no child specification with the specified \fIId\fR\&, the function returns \fI{error,not_found}\fR\&\&.
.LP
For a description of \fISupRef\fR\&, see \fB\fIstart_child/2\fR\&\fR\&\&.
.RE

.LP
.nf

.B
which_children(SupRef) -> [{Id, Child, Type, Modules}]
.br
.fi
.br
.RS
.LP
Types:

.RS 3
SupRef = \fBsup_ref()\fR\&
.br
Id = \fBchild_id()\fR\& | undefined
.br
Child = \fBchild()\fR\& | restarting
.br
Type = \fBworker()\fR\&
.br
Modules = \fBmodules()\fR\&
.br
.RE
.RE
.RS
.LP
Returns a newly created list with information about all child specifications and child processes belonging to supervisor \fISupRef\fR\&\&.
.LP
Notice that calling this function when supervising many childrens under low memory conditions can cause an out of memory exception\&.
.LP
For a description of \fISupRef\fR\&, see \fB\fIstart_child/2\fR\&\fR\&\&.
.LP
The following information is given for each child specification/process:
.RS 2
.TP 2
*
\fIId\fR\& - As defined in the child specification or \fIundefined\fR\& for a \fIsimple_one_for_one\fR\& supervisor\&.
.LP
.TP 2
*
\fIChild\fR\& - The pid of the corresponding child process, the atom \fIrestarting\fR\& if the process is about to be restarted, or \fIundefined\fR\& if there is no such process\&.
.LP
.TP 2
*
\fIType\fR\& - As defined in the child specification\&.
.LP
.TP 2
*
\fIModules\fR\& - As defined in the child specification\&.
.LP
.RE

.RE

.SH "CALLBACK FUNCTIONS"

.LP
The following function must be exported from a \fIsupervisor\fR\& callback module\&.
.SH EXPORTS
.LP
.B
Module:init(Args) -> Result
.br
.RS
.LP
Types:

.RS 3
Args = term()
.br
Result = {ok,{SupFlags,[ChildSpec]}} | ignore
.br
 SupFlags = \fB\fIsup_flags()\fR\&\fR\&
.br
 ChildSpec = \fB\fIchild_spec()\fR\&\fR\&
.br
.RE
.RE
.RS
.LP
Whenever a supervisor is started using \fB\fIstart_link/2,3\fR\&\fR\&, this function is called by the new process to find out about restart strategy, maximum restart intensity, and child specifications\&.
.LP
\fIArgs\fR\& is the \fIArgs\fR\& argument provided to the start function\&.
.LP
\fISupFlags\fR\& is the supervisor flags defining the restart strategy and maximum restart intensity for the supervisor\&. \fI[ChildSpec]\fR\& is a list of valid child specifications defining which child processes the supervisor must start and monitor\&. See the discussion in section \fB\fISupervision Principles\fR\&\fR\& earlier\&.
.LP
Notice that when the restart strategy is \fIsimple_one_for_one\fR\&, the list of child specifications must be a list with one child specification only\&. (The child specification identifier is ignored\&.) No child process is then started during the initialization phase, but all children are assumed to be started dynamically using \fB\fIstart_child/2\fR\&\fR\&\&.
.LP
The function can also return \fIignore\fR\&\&.
.LP
Notice that this function can also be called as a part of a code upgrade procedure\&. Therefore, the function is not to have any side effects\&. For more information about code upgrade of supervisors, see section \fBChanging a Supervisor\fR\& in OTP Design Principles\&.
.RE

.SH "SEE ALSO"

.LP
\fB\fIgen_event(3erl)\fR\&\fR\&, \fB\fIgen_fsm(3erl)\fR\&\fR\&, \fB\fIgen_statem(3erl)\fR\&\fR\&, \fB\fIgen_server(3erl)\fR\&\fR\&, \fB\fIsys(3erl)\fR\&\fR\&