5 Supervisor Behaviour

A supervisor is responsible for starting, stopping and
monitoring its child processes. The basic idea of a supervisor is
that it should keep its child processes alive by restarting them
when necessary.

Which child processes to start and monitor is specified by a
list of child specifications.
The child processes are started in the order specified by this
list, and terminated in the reversed order.

one_for_one

one_for_all

If a child process terminates, all other child processes are
terminated and then all child processes, including
the terminated one, are restarted.

Figure
5.2:
One_For_All Supervision

rest_for_one

If a child process terminates, the 'rest' of the child
processes -- i.e. the child processes after the terminated
process in start order -- are terminated. Then the terminated
child process and the rest of the child processes are restarted.

The supervisors have a built-in mechanism to limit the number of
restarts which can occur in a given time interval. This is
determined by the values of the two parameters MaxR and
MaxT in the start specification returned by the callback
function init:

init(...) ->
{ok, {{RestartStrategy, MaxR, MaxT},
[ChildSpec, ...]}}.

If more than MaxR number of restarts occur in the last
MaxT seconds, then the supervisor terminates all the child
processes and then itself.

When the supervisor terminates, then the next higher level
supervisor takes some action. It either restarts the terminated
supervisor, or terminates itself.

The intention of the restart mechanism is to prevent a situation
where a process repeatedly dies for the same reason, only to be
restarted again.

Id is a name that is used to identify the child
specification internally by the supervisor.

StartFunc defines the function call used to start
the child process. It is a module-function-arguments tuple
used as apply(M, F, A).

It should be (or result in) a call to
supervisor:start_link, gen_server:start_link,
gen_fsm:start_link or gen_event:start_link.
(Or a function compliant with these functions, see
supervisor(3) for details.

Restart defines when a terminated child process should
be restarted.

A permanent child process is always restarted.

A temporary child process is never restarted.

A transient child process is restarted only if it
terminates abnormally, i.e. with another exit reason than
normal.

An integer timeout value means that the supervisor tells
the child process to terminate by calling
exit(Child, shutdown) and then waits for an exit
signal back. If no exit signal is received within
the specified time, the child process is unconditionally
terminated using exit(Child, kill).

If the child process is another supervisor, it should be
set to infinity to give the subtree enough time to
shutdown.

Type specifies if the child process is a supervisor or
a worker.

Modules should be a list with one element
[Module], where Module is the name of
the callback module, if the child process is a supervisor,
gen_server or gen_fsm. If the child process is a gen_event,
Modules should be dynamic.

This information is used by the release handler during
upgrades and downgrades, see
Release Handling.

Example: The child specification to start the server ch3
in the example above looks like:

{ch3,
{ch3, start_link, []},
permanent, brutal_kill, worker, [ch3]}

Example: A child specification to start the event manager from
the chapter about
gen_event:

Both the server and event manager are registered processes which
can be expected to be accessible at all times, thus they are
specified to be permanent.

ch3 does not need to do any cleaning up before
termination, thus no shutdown time is needed but
brutal_kill should be sufficient. error_man may
need some time for the event handlers to clean up, thus
Shutdown is set to 5000 ms.

In the example above, the supervisor is started by calling
ch_sup:start_link():

start_link() ->
supervisor:start_link(ch_sup, []).

ch_sup:start_link calls the function
supervisor:start_link/2. This function spawns and links to
a new process, a supervisor.

The first argument, ch_sup, is the name of
the callback module, that is the module where the init
callback function is located.

The second argument, [], is a term which is passed as-is to
the callback function init. Here, init does not
need any indata and ignores the argument.

In this case, the supervisor is not registered. Instead its pid
must be used. A name can be specified by calling
supervisor:start_link({local, Name}, Module, Args) or
supervisor:start_link({global, Name}, Module, Args).

The new supervisor process calls the callback function
ch_sup:init([]). init is expected to return
{ok, StartSpec}:

Child processes added using start_child/2 behave in
the same manner as the other child processes, with the following
important exception: If a supervisor dies and is re-created, then
all child processes which were dynamically added to the supervisor
will be lost.

When started, the supervisor will not start any child processes.
Instead, all child processes are added dynamically by calling:

supervisor:start_child(Sup, List)

Sup is the pid, or name, of the supervisor.
List is an arbitrary list of terms which will be added to
the list of arguments specified in the child specification. If
the start function is specified as {M, F, A}, then
the child process is started by calling
apply(M, F, A++List).

For example, adding a child to simple_sup above:

supervisor:start_child(Pid, [id1])

results in the child process being started by calling
apply(call, start_link, []++[id1]), or actually:

Since the supervisor is part of a supervision tree, it will
automatically be terminated by its supervisor. When asked to
shutdown, it will terminate all child processes in reversed start
order according to the respective shutdown specifications, and
then terminate itself.