Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       supervisor - Generic Supervisor Behaviour

DESCRIPTION

       A  behaviour  module  for  implementing  a  supervisor,  a  process which 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 gen_event,
       gen_fsm, or gen_server behaviours. A supervisor implemented using this module will have  a
       standard  set  of  interface  functions  and  include  functionality for tracing and error
       reporting. Supervisors are used to  build  an  hierarchical  process  structure  called  a
       supervision  tree,  a  nice  way  to  structure a fault tolerant application. Refer to OTP
       Design Principles for more information.

       A supervisor assumes the definition of which child processes to supervise to be located in
       a callback module exporting a pre-defined set of functions.

       Unless  otherwise  stated,  all  functions  in  this  module  will  fail  if the specified
       supervisor does not exist or if bad arguments are given.

SUPERVISION PRINCIPLES

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

       The children of a supervisor is defined as  a  list  of  child  specifications.  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.

       A supervisor can have one of the following restart strategies:

         * one_for_one - if one child process terminates and should be restarted, only that child
           process is affected.

         * one_for_all - if one child process terminates and should be restarted, all other child
           processes are terminated and then all child processes are restarted.

         * rest_for_one  - if one child process terminates and should be restarted, the 'rest' of
           the child processes -- i.e. 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.

         * simple_one_for_one - a simplified one_for_one supervisor, where  all  child  processes
           are dynamically added instances of the same process type, i.e. running the same code.

           The  functions  delete_child/2  and restart_child/2 are invalid for simple_one_for_one
           supervisors and will return {error,simple_one_for_one}  if  the  specified  supervisor
           uses this restart strategy.

           The  function  terminate_child/2  can  be  used  for children under simple_one_for_one
           supervisors by giving the child's pid() as the second argument. If instead  the  child
           specification     identifier     is     used,     terminate_child/2     will    return
           {error,simple_one_for_one}.

           Because a simple_one_for_one supervisor could have many children, it  shuts  them  all
           down  at  same  time. So, order in which they are stopped is not defined. For the same
           reason, it could have an overhead with regards to the Shutdown strategy.

       To prevent a supervisor from getting into an infinite loop of child  process  terminations
       and  restarts,  a  maximum  restart frequency is defined using two integer values MaxR and
       MaxT. If more than MaxR restarts occur within MaxT seconds, the supervisor terminates  all
       child processes and then itself.

       This is the type definition of a child specification:

       child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules}
        Id = term()
        StartFunc = {M,F,A}
         M = F = atom()
         A = [term()]
        Restart = permanent | transient | temporary
        Shutdown = brutal_kill | int()>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.

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

           The  start  function  must  create  and  link  to the child process, and should return
           {ok,Child} or {ok,Child,Info} where Child is the pid of the child process and Info  an
           arbitrary term which is ignored by the supervisor.

           The  start function can also return ignore if the child process for some reason cannot
           be started, in which case the child specification  will  be  kept  by  the  supervisor
           (unless it is a temporary child) but the non-existing child process will be ignored.

           If something goes wrong, the function may also return an error tuple {error,Error}.

           Note  that  the  start_link  functions  of the different behaviour modules fulfill the
           above requirements.

         * Restart defines when a terminated child process should be restarted. A permanent child
           process  should  always  be  restarted,  a  temporary  child  process  should never be
           restarted (even when the supervisor's restart strategy is rest_for_one or  one_for_all
           and  a  sibling's death causes the temporary process to be terminated) and a transient
           child process should be restarted only if it terminates abnormally, i.e. with  another
           exit reason than normal, shutdown or {shutdown,Term}.

         * Shutdown defines how a child process should be terminated. brutal_kill means the child
           process will be unconditionally terminated using exit(Child,kill). An integer  timeout
           value  means  that  the supervisor will tell the child process to terminate by calling
           exit(Child,shutdown) and then wait for an exit signal with reason shutdown  back  from
           the  child  process.  If  no  exit  signal  is received within the specified number of
           milliseconds, the child process is unconditionally terminated using exit(Child,kill).

           If the child process is another supervisor, Shutdown should be set to infinity to give
           the  subtree  ample time to shutdown. It is also allowed to set it to infinity, if the
           child process is a worker.

     Warning:
         Be careful by setting the Shutdown strategy to infinity 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.

           Note  that  all  child  processes  implemented using the standard OTP behavior modules
           automatically adhere to the shutdown protocol.

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

         * Modules is used by the release handler during  code  replacement  to  determine  which
           processes are using a certain module. As a rule of thumb Modules should be a list with
           one element [Module], where Module is the callback module, if the child process  is  a
           supervisor,  gen_server  or  gen_fsm.  If  the  child  process  is  an  event  manager
           (gen_event) with a dynamic set of callback modules, Modules should be dynamic. See OTP
           Design Principles for more information about release handling.

         * Internally,  the supervisor also keeps track of the pid Child of the child process, or
           undefined if no pid exists.

DATA TYPES

       child() = undefined | pid()

       child_id() = term()

              Not a pid().

       child_spec() =
           {Id :: child_id(),
            StartFunc :: mfargs(),
            Restart :: restart(),
            Shutdown :: shutdown(),
            Type :: worker(),
            Modules :: modules()}

       mfargs() =
           {M :: module(), F :: atom(), A :: [term()] | undefined}

              A (the argument list) has the value undefined if Restart is temporary.

       modules() = [module()] | dynamic

       restart() = permanent | transient | temporary

       shutdown() = brutal_kill | timeout()

       strategy() = one_for_all
                  | one_for_one
                  | rest_for_one
                  | simple_one_for_one

       sup_ref() = (Name :: atom())
                 | {Name :: atom(), Node :: node()}
                 | {global, Name :: atom()}
                 | pid()

       worker() = worker | supervisor

EXPORTS

       start_link(Module, Args) -> startlink_ret()

       start_link(SupName, Module, Args) -> startlink_ret()

              Types:

                 SupName = sup_name()
                 Module = module()
                 Args = term()
                 startlink_ret() = {ok, pid()}
                                 | ignore
                                 | {error, startlink_err()}
                 startlink_err() = {already_started, pid()}
                                 | {shutdown, term()}
                                 | term()
                 sup_name() = {local, Name :: atom()} | {global, Name :: atom()}

              Creates a supervisor process as part of a  supervision  tree.  The  function  will,
              among  other  things,  ensure  that the supervisor is linked to the calling process
              (its supervisor).

              The created supervisor process  calls  Module:init/1  to  find  out  about  restart
              strategy,  maximum  restart frequency and child processes. To ensure a synchronized
              start-up procedure, start_link/2,3 does not return until Module:init/1 has returned
              and all child processes have been started.

              If  SupName={local,Name}  the  supervisor  is  registered  locally  as  Name  using
              register/2. If SupName={global,Name} the supervisor is registered globally as  Name
              using   global:register_name/2.  If  SupName={via,Module,Name}  the  supervisor  is
              registered as Name using the registry represented by Module.  The  Module  callback
              should  export  the  functions register_name/2, unregister_name/1 and send/2, which
              should behave like the corresponding functions in global.  Thus,  {via,global,Name}
              is a valid reference.

              If no name is provided, the supervisor is not registered.

              Module is the name of the callback module.

              Args is an arbitrary term which is passed as the argument to Module:init/1.

              If  the  supervisor  and  its child processes are successfully created (i.e. if all
              child process start functions return {ok,Child}, {ok,Child,Info},  or  ignore)  the
              function returns {ok,Pid}, where Pid is the pid of the supervisor. If there already
              exists   a   process   with   the   specified   SupName   the   function    returns
              {error,{already_started,Pid}}, where Pid is the pid of that process.

              If  Module:init/1  returns  ignore,  this  function  returns ignore as well and the
              supervisor terminates with reason normal. If  Module:init/1  fails  or  returns  an
              incorrect  value,  this  function  returns  {error,Term}  where Term is a term with
              information about the error, and the supervisor terminates with reason Term.

              If any child process start function fails or returns an error tuple or an erroneous
              value, the supervisor will first terminate all already started child processes with
              reason shutdown and then terminate itself and return {error, {shutdown, Reason}}.

       start_child(SupRef, ChildSpec) -> startchild_ret()

              Types:

                 SupRef = sup_ref()
                 ChildSpec = child_spec() | (List :: [term()])
                 child_spec() =
                     {Id :: child_id(),
                      StartFunc :: mfargs(),
                      Restart :: restart(),
                      Shutdown :: shutdown(),
                      Type :: worker(),
                      Modules :: modules()}
                 startchild_ret() = {ok, Child :: child()}
                                  | {ok, Child :: child(), Info :: term()}
                                  | {error, startchild_err()}
                 startchild_err() = already_present
                                  | {already_started, Child :: child()}
                                  | term()

              Dynamically adds a child specification to the supervisor SupRef  which  starts  the
              corresponding child process.

              SupRef can be:

                * the pid,

                * Name, if the supervisor is locally registered,

                * {Name,Node}, if the supervisor is locally registered at another node, or

                * {global,Name}, if the supervisor is globally registered.

                * {via,Module,Name},  if  the  supervisor  is  registered  through an alternative
                  process registry.

              ChildSpec should be a  valid  child  specification  (unless  the  supervisor  is  a
              simple_one_for_one  supervisor,  see  below).  The child process will be started by
              using the start function as defined in the child specification.

              If the case of a simple_one_for_one supervisor, the child specification defined  in
              Module:init/1  will  be  used  and ChildSpec should instead be an arbitrary list of
              terms List. The child process will  then  be  started  by  appending  List  to  the
              existing  start  function  arguments,  i.e.  by  calling apply(M, F, A++List) where
              {M,F,A} is the start function defined in the child specification.

              If there already exists a child specification with the specified Id,  ChildSpec  is
              discarded     and     the     function     returns    {error,already_present}    or
              {error,{already_started,Child}}, depending on if the corresponding child process is
              running or not.

              If  the  child  process  start  function returns {ok,Child} or {ok,Child,Info}, the
              child specification and pid is added to the supervisor and the function returns the
              same value.

              If  the  child  process  start  function returns ignore, the child specification is
              added to the supervisor, the pid is set  to  undefined  and  the  function  returns
              {ok,undefined}.

              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
              {error,Error}  where  Error  is  a  term containing information about the error and
              child specification.

       terminate_child(SupRef, Id) -> Result

              Types:

                 SupRef = sup_ref()
                 Id = pid() | child_id()
                 Result = ok | {error, Error}
                 Error = not_found | simple_one_for_one

              Tells the supervisor SupRef to terminate the given child.

              If the supervisor is not simple_one_for_one, Id must  be  the  child  specification
              identifier.  The  process,  if  there  is  one,  is  terminated and, unless it is a
              temporary child, the child specification is  kept  by  the  supervisor.  The  child
              process  may  later  be  restarted by the supervisor. The child process can also be
              restarted explicitly by calling restart_child/2. Use delete_child/2 to  remove  the
              child specification.

              If  the  child  is  temporary,  the  child  specification is deleted as soon as the
              process  terminates.  This  means  that   delete_child/2   has   no   meaning   and
              restart_child/2 can not be used for these children.

              If  the  supervisor  is simple_one_for_one, Id must be the child process' pid(). If
              the specified process is alive, but is not a child of  the  given  supervisor,  the
              function  will  return  {error,not_found}. If the child specification identifier is
              given   instead   instead    of    a    pid(),    the    function    will    return
              {error,simple_one_for_one}.

              If successful, the function returns ok. If there is no child specification with the
              specified Id, the function returns {error,not_found}.

              See start_child/2 for a description of SupRef.

       delete_child(SupRef, Id) -> Result

              Types:

                 SupRef = sup_ref()
                 Id = child_id()
                 Result = ok | {error, Error}
                 Error = running | restarting | not_found | simple_one_for_one

              Tells the supervisor SupRef to delete the child specification identified by Id. The
              corresponding child process must not be running, use terminate_child/2 to terminate
              it.

              See start_child/2 for a description of SupRef.

              If successful, the function returns ok. If the child specification identified by Id
              exists but the corresponding child process is running or about to be restarted, the
              function returns {error,running} or {error,restarting} respectively. If  the  child
              specification   identified   by   Id   does   not   exist,   the  function  returns
              {error,not_found}.

       restart_child(SupRef, Id) -> Result

              Types:

                 SupRef = sup_ref()
                 Id = child_id()
                 Result = {ok, Child :: child()}
                        | {ok, Child :: child(), Info :: term()}
                        | {error, Error}
                 Error = running
                       | restarting
                       | not_found
                       | simple_one_for_one
                       | term()

              Tells the supervisor SupRef to restart a child process corresponding to  the  child
              specification  identified  by  Id.  The  child  specification  must  exist  and the
              corresponding child process must not be running.

              Note that for temporary children, the child specification is automatically  deleted
              when the child terminates, and thus it is not possible to restart such children.

              See start_child/2 for a description of SupRef.

              If  the  child  specification identified by Id does not exist, the function returns
              {error,not_found}. If the child specification exists but the corresponding  process
              is already running, the function returns {error,running}.

              If  the child process start function returns {ok,Child} or {ok,Child,Info}, the pid
              is added to the supervisor and the function returns the same value.

              If the child process  start  function  returns  ignore,  the  pid  remains  set  to
              undefined and the function returns {ok,undefined}.

              If  the  child process start function returns an error tuple or an erroneous value,
              or if it fails, the function returns {error,Error} where Error is a term containing
              information about the error.

       which_children(SupRef) -> [{Id, Child, Type, Modules}]

              Types:

                 SupRef = sup_ref()
                 Id = child_id() | undefined
                 Child = child() | restarting
                 Type = worker()
                 Modules = modules()

              Returns  a  newly  created list with information about all child specifications and
              child processes belonging to the supervisor SupRef.

              Note that calling this function when supervising a large number of  children  under
              low memory conditions can cause an out of memory exception.

              See start_child/2 for a description of SupRef.

              The information given for each child specification/process is:

                * Id  -  as  defined  in  the  child  specification or undefined in the case of a
                  simple_one_for_one supervisor.

                * Child - the pid of the corresponding child process, the atom restarting if  the
                  process is about to be restarted or undefined if there is no such process.

                * Type - as defined in the child specification.

                * Modules - as defined in the child specification.

       count_children(SupRef) -> PropListOfCounts

              Types:

                 SupRef = sup_ref()
                 PropListOfCounts = [Count]
                 Count = {specs, ChildSpecCount :: integer() >= 0}
                       | {active, ActiveProcessCount :: integer() >= 0}
                       | {supervisors,
                          ChildSupervisorCount :: integer() >= 0}
                       | {workers, ChildWorkerCount :: integer() >= 0}

              Returns  a  property  list  (see  proplists)  containing the counts for each of the
              following elements of the supervisor's child specifications and managed processes:

                * specs - the total count of children, dead or alive.

                * active - the count of all actively running  child  processes  managed  by  this
                  supervisor.

                * supervisors  -  the  count of all children marked as child_type = supervisor in
                  the spec list, whether or not the child process is still alive.

                * workers - the count of all children marked as child_type = worker in  the  spec
                  list, whether or not the child process is still alive.

       check_childspecs(ChildSpecs) -> Result

              Types:

                 ChildSpecs = [child_spec()]
                 Result = ok | {error, Error :: term()}

              This function takes a list of child specification as argument and returns ok if all
              of them are syntactically correct, or {error,Error} otherwise.

CALLBACK FUNCTIONS

       The following functions should be exported from a supervisor callback module.

EXPORTS

       Module:init(Args) -> Result

              Types:

                 Args = term()
                 Result = {ok,{{RestartStrategy,MaxR,MaxT},[ChildSpec]}} | ignore
                  RestartStrategy = strategy()
                  MaxR = integer()>=0
                  MaxT = integer()>0
                  ChildSpec = child_spec()

              Whenever a supervisor is started using supervisor:start_link/2,3, this function  is
              called  by  the  new  process  to  find out about restart strategy, maximum restart
              frequency and child specifications.

              Args is the Args argument provided to the start function.

              RestartStrategy is the restart strategy and  MaxR  and  MaxT  defines  the  maximum
              restart  frequency  of  the  supervisor.  [ChildSpec]  is  a  list  of  valid child
              specifications defining which child  processes  the  supervisor  should  start  and
              monitor. See the discussion about Supervision Principles above.

              Note  that  when  the  restart  strategy  is  simple_one_for_one, the list of child
              specifications must be a list  with  one  child  specification  only.  (The  Id  is
              ignored). No child process is then started during the initialization phase, but all
              children are assumed to be started dynamically using supervisor:start_child/2.

              The function may also return ignore.

SEE ALSO

       gen_event(3erl), gen_fsm(3erl), gen_server(3erl), sys(3erl)