OTP设计原则:Supervisor行为

5 Supervisor Behaviour

This section should be read in conjunction with supervisor(3), where all details about the supervisor behaviour is given.

这节应该和 supervisor(3)结合来读,所有关于supervisor行为的细节都在那儿。

5.1 Supervision Principles

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.
supervisor的职责是启动,停止和监视它的子进程。最简单的supervisor就是必要时通过重启它的子进程，来保证它们一直活着.

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.

重启和监视哪些子进程，由子进程说明列表来定义。子进程按列表顺序来启动，而终止时是相反的顺序。

5.2 Example

The callback module for a supervisor starting the server from the gen_server chapter could look like this:

 
 

  
  java 代码
 
 
 
 
-module(ch_sup).
-behaviour(supervisor).

-export([start_link/0]).
-export([init/1]).

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

init(_Args) ->
    {ok, {{one_for_one, 1, 60},
          [{ch3, {ch3, start_link, []},
            permanent, brutal_kill, worker, [ch3]}]}}.
    

one_for_one is the restart strategy.

one_for_one是重启策略.

1 and 60 defines the maximum restart frequency.

1和60定义了最大重启频率

The tuple {ch3, ...} is a child specification.

元组 {ch3, ...}是一个子进程说明.

5.3 Restart Strategy

5.3 重启策略

5.3.1 one_for_one

If a child process terminates, only that process is restarted.

如果一个子进程终止了, 只重启此子进程自身。

One_For_One Supervision

5.3.2 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.
如果一个子进程终止了,其它子进程全部被终止。然后所有子进程，包括终止了的那个，全部重启。

One_For_All Supervision

5.3.3 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.

如果一个子进程终止了，它的余下子进程(即启动时在它后面的子进程)全部被终止。然后它和它的余下子进程全部重启。

5.4 Maximum Restart Frequency

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:

 
 

  
  java 代码
 
 
 
 
init(...) ->
    {ok, {{RestartStrategy, MaxR, MaxT},
          [ChildSpec, ...]}}.
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.

5.5 Child Specification

This is the type definition for a child specification:

{Id, StartFunc, Restart, Shutdown, Type, Modules}
    Id = term()
    StartFunc = {M, F, A}
        M = F = atom()
        A = [term()]
    Restart = permanent | transient | temporary
    Shutdown = brutal_kill | integer() >=0 | infinity
    Type = worker | supervisor
    Modules = [Module] | dynamic
        Module = atom()
    

• Id is a name that is used to identify the child specification internally by the supervisor.
  Id 是一个被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.
•   Shutdown defines how a child process should be terminated.
  
  • brutal_kill means the child process is unconditionally terminated using exit(Child, kill).
  • 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.
    如子进程是另外一个管理者,应该把它设为infinity，让它的子树有足够的时间来关闭。
• 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:

{error_man,
 {gen_event, start_link, [{local, error_man}]},
 permanent, 5000, worker, dynamic}
    

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.

Example: A child specification to start another supervisor:

{sup,
 {sup, start_link, []},
 transient, infinity, supervisor, [sup]}
    

5.6 Starting a Supervisor

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

 
 

  
  java 代码
 
 
 
 
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}:

 
 

  
  java 代码
 
 
 
 
init(_Args) ->
    {ok, {{one_for_one, 1, 60},
          [{ch3, {ch3, start_link, []},
            permanent, brutal_kill, worker, [ch3]}]}}.

The supervisor then starts all its child processes according to the child specifications in the start specification. In this case there is one child process, ch3.

Note that supervisor:start_link is synchronous. It does not return until all child processes have been started.

5.7 Adding a Child Process

In addition to the static supervision tree, we can also add dynamic child processes to an existing supervisor with the following call:

 
 

  
  java 代码
 
 
 
 
supervisor:start_child(Sup, ChildSpec)
    

Sup is the pid, or name, of the supervisor. ChildSpec is a child specification.

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.

5.8 Stopping a Child Process

Any child process, static or dynamic, can be stopped in accordance with the shutdown specification:

 
 

  
  java 代码
 
 
 
 
supervisor:terminate_child(Sup, Id)
    

The child specification for a stopped child process is deleted with the following call:

 
 

  
  java 代码
 
 
 
 
supervisor:delete_child(Sup, Id)
    

Sup is the pid, or name, of the supervisor. Id is the id specified in the child specification.

As with dynamically added child processes, the effects of deleting a static child process is lost if the supervisor itself restarts.

5.9 Simple-One-For-One Supervisors

A supervisor with restart strategy simple_one_for_one is a simplified one_for_one supervisor, where all child processes are dynamically added instances of the same process.

Example of a callback module for a simple_one_for_one supervisor:

 
 

  
  java 代码
 
 
 
 
-module(simple_sup).
-behaviour(supervisor).

-export([start_link/0]).
-export([init/1]).

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

init(_Args) ->
    {ok, {{simple_one_for_one, 0, 1},
          [{call, {call, start_link, []},
            temporary, brutal_kill, worker, [call]}]}}.
    

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

 
 

  
  java 代码
 
 
 
 
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:

 
 

  
  java 代码
 
 
 
 
supervisor:start_child(Pid, [id1])
    

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

 
 

  
  java 代码
 
 
 
 
call:start_link(id1)
    

5.10 Stopping

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.