Unix/Linux Go Back    


Linux 2.6 - man page for supervisor (linux section 3erl)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


supervisor(3erl)		     Erlang Module Definition			 supervisor(3erl)

NAME
       supervisor - Generic Supervisor Behaviour

DESCRIPTION
       A  behaviour  module  for implementing a supervisor, a process which supervises other pro-
       cesses 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 super-
       vision  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 supervi-
       sor 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 accord-
       ing 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  terminate_child/2 , 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 spec-
	   ified supervisor uses this restart 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 super-
	   visor.

	 * 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 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  and  a  transient  child	process should be 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 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  mil-
	   liseconds, 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.

	   Important note on simple-one-for-one supervisors: The dynamically created  child  pro-
	   cesses  of  a  simple-one-for-one  supervisor are not explicitly killed, regardless of
	   shutdown strategy, but are expected to terminate when the supervisor  does  (that  is,
	   when an exit signal from the parent process is received).

	   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 pro-
	   cesses  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.

EXPORTS
       start_link(Module, Args) -> Result
       start_link(SupName, Module, Args) -> Result

	      Types  SupName = {local,Name} | {global,Name}
		     Name = atom()
		     Module = atom()
		     Args = term()
		     Result = {ok,Pid} | ignore | {error,Error}
		     Pid = pid()
		     Error = {already_started,Pid}} | shutdown | term()

	      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 strat-
	      egy, 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 regis-
	      ter/2 . If SupName={global,Name} the supervisor  is  registered  globally  as  Name
	      using global:register_name/2 . If no name is provided, the supervisor is not regis-
	      tered.

	      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 function returns {error,shutdown}  and  the  supervisor  terminates  all
	      started child processes and then itself with reason shutdown .

       start_child(SupRef, ChildSpec) -> Result

	      Types  SupRef = Name | {Name,Node} | {global,Name} | pid()
		     Name = Node = atom()
		     ChildSpec = child_spec() | [term()]
		     Result = {ok,Child} | {ok,Child,Info} | {error,Error}
		     Child = pid() | undefined
		     Info = term()
		     Error = already_present | {already_started,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.

	      ChildSpec should be a valid child specification (unless the supervisor  is  a  sim-
	      ple_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 exist-
	      ing 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 = Name | {Name,Node} | {global,Name} | pid()
		     Name = Node = atom()
		     Id = term()
		     Result = ok | {error,Error}
		     Error = not_found | simple_one_for_one

	      Tells the supervisor SupRef to terminate the child  process  corresponding  to  the
	      child  specification identified by Id . The process, if there is one, is terminated
	      but the child specification is kept by the supervisor. This means  that  the  child
	      process  may be 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.

	      See start_child/2 for a description of SupRef .

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

       delete_child(SupRef, Id) -> Result

	      Types  SupRef = Name | {Name,Node} | {global,Name} | pid()
		     Name = Node = atom()
		     Id = term()
		     Result = ok | {error,Error}
		     Error = running | 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 ter-
	      minate 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, the function returns
	      {error,running} . If the child specification identified by Id does not  exist,  the
	      function returns {error,not_found} .

       restart_child(SupRef, Id) -> Result

	      Types  SupRef = Name | {Name,Node} | {global,Name} | pid()
		     Name = Node = atom()
		     Id = term()
		     Result = {ok,Child} | {ok,Child,Info} | {error,Error}
		     Child = pid() | undefined
		     Error = running | 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  corre-
	      sponding child process must not be running.

	      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  unde-
	      fined 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 = Name | {Name,Node} | {global,Name} | pid()
		     Name = Node = atom()
		     Id = term() | undefined
		     Child = pid() | undefined
		     Type = worker | supervisor
		     Modules = [Module] | dynamic
		     Module = atom()

	      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 sim-
		  ple_one_for_one supervisor.

		* Child - the pid of the corresponding child process, 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 = Name | {Name,Node} | {global,Name} | pid()
		     Name = Node = atom()
		     PropListOfCounts  =  [{specs, ChildSpecCount}, {active, ActiveProcessCount},
		     {supervisors, ChildSupervisorCount}, {workers, ChildWorkerCount}]

	      Returns a property list (see proplists ) containing the counts for each of the fol-
	      lowing 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([ChildSpec]) -> Result

	      Types  ChildSpec = child_spec()
		     Result = ok | {error,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   =   one_for_all	 |  one_for_one  |  rest_for_one  |  sim-
		     ple_one_for_one
		     MaxR = MaxT = int()>=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 fre-
	      quency 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 specifi-
	      cations 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 spec-
	      ifications 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)

Ericsson AB				  stdlib 1.17.3 			 supervisor(3erl)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 07:04 AM.