File: sup_princ.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (445 lines) | stat: -rw-r--r-- 13,199 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>Supervisor Behaviour</TITLE>
  <SCRIPT type="text/javascript" src="../../doc/erlresolvelinks.js">
</SCRIPT>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<CENTER>
<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif"></A>
</CENTER>
<A NAME="5"><!-- Empty --></A>
<H2>5 Supervisor Behaviour</H2>

<P>This section should be read in conjunction with
<CODE>supervisor(3)</CODE>, where all details about the supervisor
behaviour is given.<A NAME="5.1"><!-- Empty --></A>
<H3>5.1 Supervision Principles</H3>

<P>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.
<P>Which child processes to start and monitor is specified by a
list of <A HREF="#spec">child specifications</A>.
The child processes are started in the order specified by this
list, and terminated in the reversed order.<A NAME="5.2"><!-- Empty --></A>
<H3>5.2 Example</H3>

<P>The callback module for a supervisor starting the server from
the <A HREF="gen_server.html#ex">gen_server chapter</A>
could look like this:<A NAME="ex"><!-- Empty --></A>
<PRE>
-module(ch_sup).
-behaviour(supervisor).

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

start_link() -&#62;
    supervisor:start_link(ch_sup, []).

init(_Args) -&#62;
    {ok, {{one_for_one, 1, 60},
          [{ch3, {ch3, start_link, []},
            permanent, brutal_kill, worker, [ch3]}]}}.
    
</PRE>

<P><CODE>one_for_one</CODE> is the <A HREF="#strategy">restart
        strategy</A>.
<P>1 and 60 defines the <A HREF="#frequency">maximum restart
        frequency</A>.
<P>The tuple <CODE>{ch3, ...}</CODE> is a <A HREF="#spec">child
        specification</A>.<A NAME="strategy"><!-- Empty --></A><A NAME="5.3"><!-- Empty --></A>
<H3>5.3 Restart Strategy</H3>
<A NAME="5.3.1"><!-- Empty --></A>
<H4>5.3.1 one_for_one</H4>

<P>If a child process terminates, only that process is restarted.

<P>
<CENTER>
<IMG ALT="sup4" SRC="sup4.gif"><BR>
<EM><A NAME="sup4"><!-- Empty --></A>One_For_One Supervision
</EM>

</CENTER>
<A NAME="5.3.2"><!-- Empty --></A>
<H4>5.3.2 one_for_all</H4>

<P>If a child process terminates, all other child processes are
        terminated and then all child processes, including
        the terminated one, are restarted.
<P>
<CENTER>
<IMG ALT="sup5" SRC="sup5.gif"><BR>
<EM><A NAME="sup5"><!-- Empty --></A>One_For_All Supervision
</EM>

</CENTER>
<A NAME="5.3.3"><!-- Empty --></A>
<H4>5.3.3 rest_for_one</H4>

<P>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.
<A NAME="frequency"><!-- Empty --></A><A NAME="5.4"><!-- Empty --></A>
<H3>5.4 Maximum Restart Frequency</H3>

<P>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 <CODE>MaxR</CODE> and
<CODE>MaxT</CODE> in the start specification returned by the callback
function <CODE>init</CODE>:
<PRE>
init(...) -&#62;
    {ok, {{RestartStrategy, MaxR, MaxT},
          [ChildSpec, ...]}}.
    
</PRE>

<P>If more than <CODE>MaxR</CODE> number of restarts occur in the last
<CODE>MaxT</CODE> seconds, then the supervisor terminates all the child
processes and then itself.
<P>When the supervisor terminates, then the next higher level
supervisor takes some action. It either restarts the terminated
supervisor, or terminates itself.
<P>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.<A NAME="spec"><!-- Empty --></A><A NAME="5.5"><!-- Empty --></A>
<H3>5.5 Child Specification</H3>

<P>This is the type definition for a child specification:
<PRE>
{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() &#38;gt;=0 | infinity
    Type = worker | supervisor
    Modules = [Module] | dynamic
        Module = atom()
    
</PRE>

<P>
<UL>

<LI>
        <CODE>Id</CODE> is a name that is used to identify the child
        specification internally by the supervisor.<BR>


</LI>


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

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


</LI>


<LI>
        <CODE>Restart</CODE> defines when a terminated child process should
         be restarted.<BR>

        
<UL>

<LI>
A <CODE>permanent</CODE> child process is always restarted.
         
</LI>


<LI>
A <CODE>temporary</CODE> child process is never restarted.
         
</LI>


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


</UL>


</LI>


<LI>
        <A NAME="shutdown"><!-- Empty --></A>
        <CODE>Shutdown</CODE> defines how a child process should be
         terminated.<BR>

        
<UL>

<LI>
<CODE>brutal_kill</CODE> means the child process is
         unconditionally terminated using <CODE>exit(Child, kill)</CODE>.
         
</LI>


<LI>
An integer timeout value means that the supervisor tells
         the child process to terminate by calling
         <CODE>exit(Child, shutdown)</CODE> 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 <CODE>exit(Child, kill)</CODE>.
</LI>


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


</UL>


</LI>


<LI>
        <CODE>Type</CODE> specifies if the child process is a supervisor or
         a worker.<BR>


</LI>


<LI>
        <CODE>Modules</CODE> should be a list with one element
         <CODE>[Module]</CODE>, where <CODE>Module</CODE> 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,
         <CODE>Modules</CODE> should be <CODE>dynamic</CODE>.<BR>

        This information is used by the release handler during
         upgrades and downgrades, see
         <A HREF="release_handling.html">Release Handling</A>.
        <BR>


</LI>


</UL>

<P>Example: The child specification to start the server <CODE>ch3</CODE>
in the example above looks like:
<PRE>
{ch3,
 {ch3, start_link, []},
 permanent, brutal_kill, worker, [ch3]}
    
</PRE>

<P>Example: A child specification to start the event manager from
the chapter about
<A HREF="events.html#mgr">gen_event</A>:
<PRE>
{error_man,
 {gen_event, start_link, [{local, error_man}]},
 permanent, 5000, worker, dynamic}
    
</PRE>

<P>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 <CODE>permanent</CODE>.
<P><CODE>ch3</CODE> does not need to do any cleaning up before
termination, thus no shutdown time is needed but
<CODE>brutal_kill</CODE> should be sufficient. <CODE>error_man</CODE> may
need some time for the event handlers to clean up, thus
<CODE>Shutdown</CODE> is set to 5000 ms.
<P>Example: A child specification to start another supervisor:
<PRE>
{sup,
 {sup, start_link, []},
 transient, infinity, supervisor, [sup]}
    
</PRE>
<A NAME="super_tree"><!-- Empty --></A><A NAME="5.6"><!-- Empty --></A>
<H3>5.6 Starting a Supervisor</H3>

<P>In the example above, the supervisor is started by calling
<CODE>ch_sup:start_link()</CODE>:
<PRE>
start_link() -&#62;
    supervisor:start_link(ch_sup, []).
    
</PRE>

<P><CODE>ch_sup:start_link</CODE> calls the function
<CODE>supervisor:start_link/2</CODE>. This function spawns and links to
a new process, a supervisor.
<P>
<UL>

<LI>
The first argument, <CODE>ch_sup</CODE>, is the name of
        the callback module, that is the module where the <CODE>init</CODE>
        callback function is located.
</LI>


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


</UL>

<P>In this case, the supervisor is not registered. Instead its pid
must be used. A name can be specified by calling
<CODE>supervisor:start_link({local, Name}, Module, Args)</CODE> or
<CODE>supervisor:start_link({global, Name}, Module, Args)</CODE>.
<P>The new supervisor process calls the callback function
<CODE>ch_sup:init([])</CODE>. <CODE>init</CODE> is expected to return
<CODE>{ok, StartSpec}</CODE>:
<PRE>
init(_Args) -&#62;
    {ok, {{one_for_one, 1, 60},
          [{ch3, {ch3, start_link, []},
            permanent, brutal_kill, worker, [ch3]}]}}.
    
</PRE>

<P>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, <CODE>ch3</CODE>.
<P>Note that <CODE>supervisor:start_link</CODE> is synchronous. It does
not return until all child processes have been started.<A NAME="5.7"><!-- Empty --></A>
<H3>5.7 Adding a Child Process</H3>

<P>In addition to the static supervision tree, we can also add
dynamic child processes to an existing supervisor with
the following call:
<PRE>
supervisor:start_child(Sup, ChildSpec)
    
</PRE>

<P><CODE>Sup</CODE> is the pid, or name, of the supervisor.
<CODE>ChildSpec</CODE> is a <A HREF="#spec">child
        specification</A>.
<P>Child processes added using <CODE>start_child/2</CODE> 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.<A NAME="5.8"><!-- Empty --></A>
<H3>5.8 Stopping a Child Process</H3>

<P>Any child process, static or dynamic, can be stopped in
accordance with the shutdown specification:
<PRE>
supervisor:terminate_child(Sup, Id)
    
</PRE>

<P>The child specification for a stopped child process is deleted
with the following call:
<PRE>
supervisor:delete_child(Sup, Id)
    
</PRE>

<P><CODE>Sup</CODE> is the pid, or name, of the supervisor.
<CODE>Id</CODE> is the id specified in the <A HREF="#spec">child
        specification</A>.
<P>As with dynamically added child processes, the effects of
deleting a static child process is lost if the supervisor itself
restarts.<A NAME="5.9"><!-- Empty --></A>
<H3>5.9 Simple-One-For-One Supervisors</H3>

<P>A supervisor with restart strategy <CODE>simple_one_for_one</CODE> is
a simplified one_for_one supervisor, where all child processes are
dynamically added instances of the same process.
<P>Example of a callback module for a simple_one_for_one supervisor:

<PRE>
-module(simple_sup).
-behaviour(supervisor).

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

start_link() -&#62;
    supervisor:start_link(simple_sup, []).

init(_Args) -&#62;
    {ok, {{simple_one_for_one, 0, 1},
          [{call, {call, start_link, []},
            temporary, brutal_kill, worker, [call]}]}}.
    
</PRE>

<P>When started, the supervisor will not start any child processes.
Instead, all child processes are added dynamically by calling:
<PRE>
supervisor:start_child(Sup, List)
    
</PRE>

<P><CODE>Sup</CODE> is the pid, or name, of the supervisor.
<CODE>List</CODE> 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 <CODE>{M, F, A}</CODE>, then
the child process is started by calling
<CODE>apply(M, F, A++List)</CODE>.
<P>For example, adding a child to <CODE>simple_sup</CODE> above:
<PRE>
supervisor:start_child(Pid, [id1])
    
</PRE>

<P>results in the child process being started by calling
<CODE>apply(call, start_link, []++[id1])</CODE>, or actually:
<PRE>
call:start_link(id1)
    
</PRE>
<A NAME="5.10"><!-- Empty --></A>
<H3>5.10 Stopping</H3>

<P>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.<CENTER>
<HR>
<SMALL>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>