Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
supervisor(3)		   Erlang Module Definition		 supervisor(3)

NAME
       supervisor - Generic supervisor behavior.

DESCRIPTION
       This  behavior  module provides a supervisor, a process that 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_server, or  gen_statem  be-
       haviors.	 A supervisor implemented using	this module has	a standard set
       of interface functions and include functionality	for tracing and	 error
       reporting.  Supervisors are used	to build a hierarchical	process	struc-
       ture called a supervision tree, a nice way to structure a  fault-toler-
       ant application.	For more information, see  Supervisor Behaviour	in OTP
       Design Principles.

       A supervisor expects the	definition of which child processes to	super-
       vise to be specified in a callback module exporting a predefined	set of
       functions.

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

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

       The  children of	a supervisor are defined as a list of child specifica-
       tions. 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.

       The supervisor properties are defined by	the supervisor flags. The type
       definition for the supervisor flags is as follows:

       sup_flags() = #{strategy	=> strategy(),	       % optional
		       intensity => non_neg_integer(), % optional
		       period => pos_integer()}	       % optional

       A supervisor can	have one of the	following restart strategies specified
       with the	strategy key in	the above map:

	 * one_for_one	-  If  one  child  process  terminates	and  is	 to be
	   restarted, only that	child process is affected. This	is the default
	   restart strategy.

	 * one_for_all	-  If  one  child  process  terminates	and  is	 to be
	   restarted, all other	child processes	are terminated	and  then  all
	   child processes are restarted.

	 * rest_for_one	 -  If	one  child  process  terminates	 and  is to be
	   restarted, the 'rest' of the	child processes	(that  is,  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, that is, running the same code.

	   Functions  delete_child/2  and restart_child/2 are invalid for sim-
	   ple_one_for_one supervisors and  return  {error,simple_one_for_one}
	   if the specified supervisor uses this restart strategy.

	   Function  terminate_child/2	can  be	 used  for children under sim-
	   ple_one_for_one supervisors by specifying the child's pid() as  the
	   second  argument.  If instead the child specification identifier is
	   used, terminate_child/2 return {error,simple_one_for_one}.

	   As a	simple_one_for_one supervisor can have many children, it shuts
	   them	all down asynchronously. This means that the children do their
	   cleanup in parallel,	and therefore the  order  in  which  they  are
	   stopped is not defined.

       To  prevent  a  supervisor  from	getting	into an	infinite loop of child
       process terminations and	restarts, a maximum restart intensity  is  de-
       fined using two integer values specified	with keys intensity and	period
       in the above map. Assuming the values MaxR for intensity	and  MaxT  for
       period, then, if	more than MaxR restarts	occur within MaxT seconds, the
       supervisor terminates all child processes and then itself. The termina-
       tion  reason  for  the supervisor itself	in that	case will be shutdown.
       intensity defaults to 1 and period defaults to 5.

       The type	definition of a	child specification is as follows:

       child_spec() = #{id => child_id(),	% mandatory
			start => mfargs(),	% mandatory
			restart	=> restart(),	% optional
			shutdown => shutdown(),	% optional
			type =>	worker(),	% optional
			modules	=> modules()}	% optional

       The  old	 tuple	format	is  kept  for  backwards  compatibility,   see
       child_spec(), but the map is preferred.

	 * id  is  used	 to identify the child specification internally	by the
	   supervisor.

	   The id key is mandatory.

	   Notice that this identifier on occations has	been called "name". As
	   far as possible, the	terms "identifier" or "id" are now used	but to
	   keep	backward compatibility,	some occurences	of "name" can still be
	   found, for example in error messages.

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

	   The	start  function	must create and	link to	the child process, and
	   must	return {ok,Child} or {ok,Child,Info}, where Child is  the  pid
	   of  the  child process and Info any term that is ignored by the su-
	   pervisor.

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

	   If  something goes wrong, the function can also return an error tu-
	   ple {error,Error}.

	   Notice that the start_link functions	of the different behavior mod-
	   ules	fulfill	the above requirements.

	   The start key is mandatory.

	 * restart  defines when a terminated child process must be restarted.
	   A permanent child process is	always restarted.  A  temporary	 child
	   process  is	never  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). A transient child
	   process is restarted	only if	it  terminates	abnormally,  that  is,
	   with	another	exit reason than normal, shutdown, or {shutdown,Term}.

	   The restart key is optional.	If it is not specified,	it defaults to
	   permanent.

	 * shutdown defines how	a  child  process  must	 be  terminated.  bru-
	   tal_kill means that the child process is unconditionally terminated
	   using exit(Child,kill). An integer time-out value  means  that  the
	   supervisor	tells  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,	the shutdown time must
	   be set to infinity to give the subtree ample	time to	shut down.

     Warning:
	 Setting the shutdown time to anything other than infinity for a child
	 of  type  supervisor  can  cause  a race condition where the child in
	 question unlinks its own children, but	fails to terminate them	before
	 it is killed.

	   It is also allowed to set it	to infinity, if	the child process is a
	   worker.

     Warning:
	 Be careful when setting the shutdown time 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	imple-
	 mented	in a safe way and its cleanup procedure	must always return.

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

	   The shutdown	key is optional. If it is not specified,  it  defaults
	   to  5000 if the child is of type worker and it defaults to infinity
	   if the child	is of type supervisor.

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

	   The type key	is optional. If	it is not specified,  it  defaults  to
	   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,  if  the  child  process  is	a  supervisor,	gen_server or,
	   gen_statem, this is to be a list with one element  [Module],	 where
	   Module  is  the  callback  module. If the child process is an event
	   manager (gen_event) with a dynamic set of callback  modules,	 value
	   dynamic  must be used. For more information about release handling,
	   see	Release	Handling in OTP	Design Principles.

	   The modules key is optional.	If it is not specified,	it defaults to
	   [M],	where M	comes from the child's start {M,F,A}.

	 * 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(),
	     start := mfargs(),
	     restart =>	restart(),
	     shutdown => shutdown(),
	     type => worker(),
	     modules =>	modules()} |
	   {Id :: child_id(),
	    StartFunc :: mfargs(),
	    Restart :: restart(),
	    Shutdown ::	shutdown(),
	    Type :: worker(),
	    Modules :: modules()}

	      The tuple	format is kept for backward compatibility only.	A  map
	      is preferred; see	more details above.

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

	      Value undefined for A (the argument list)	is only	to be used in-
	      ternally in supervisor. If the restart type of the child is tem-
	      porary, the process is never to be restarted and therefore there
	      is no need to store the real argument list. Value	 undefined  is
	      then stored instead.

       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_flags() =
	   #{strategy => strategy(),
	     intensity => integer() >= 0,
	     period => integer() >= 1} |
	   {RestartStrategy :: strategy(),
	    Intensity :: integer() >= 0,
	    Period :: integer()	>= 1}

	      The  tuple format	is kept	for backward compatibility only. A map
	      is preferred; see	more details above.

       sup_ref() =
	   (Name :: atom()) |
	   {Name :: atom(), Node :: node()} |
	   {global, Name :: atom()} |
	   {via, Module	:: module(), Name :: any()} |
	   pid()

       worker()	= worker | supervisor

EXPORTS
       check_childspecs(ChildSpecs) -> Result

	      Types:

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

	      Takes a list of child specification as argument and  returns  ok
	      if  all  of them are syntactically correct, otherwise {error,Er-
	      ror}.

       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. For a simple_one_for_one	super-
		  visors, no check is done to ensure that each	child  process
		  is  still alive, although the	result provided	here is	likely
		  to be	very accurate unless the supervisor is	heavily	 over-
		  loaded.

		* supervisors -	The count of all children marked as child_type
		  = supervisor in the specification list,  regardless  if  the
		  child	process	is still alive.

		* workers  -  The count	of all children	marked as child_type =
		  worker in the	specification list, regardless	if  the	 child
		  process is still alive.

	      For a description	of SupRef, see start_child/2.

       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  supervisor	SupRef to delete the child specification iden-
	      tified by	Id. The	corresponding child process must not  be  run-
	      ning. Use	terminate_child/2 to terminate it.

	      For a description	of SupRef, see start_child/2.

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

       get_childspec(SupRef, Id) -> Result

	      Types:

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

	      Returns the child	specification map for the child	identified  by
	      Id  under	supervisor SupRef. The returned	map contains all keys,
	      both mandatory and optional.

	      For a description	of SupRef, see start_child/2.

       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 supervisor SupRef to restart a child process corresponding
	      to the child specification identified by Id. The child  specifi-
	      cation  must exist, and the corresponding	child process must not
	      be running.

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

	      For a description	of SupRef, see start_child/2.

	      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 re-
	      mains 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,Er-
	      ror}, where Error	is a term containing information about the er-
	      ror.

       start_child(SupRef, ChildSpec) -> startchild_ret()

	      Types:

		 SupRef	= sup_ref()
		 ChildSpec = child_spec() | (List :: [term()])
		 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 supervisor SupRef,
	      which starts the corresponding child process.

	      SupRef can be any	of the following:

		* The pid

		* Name,	if the supervisor is locally registered

		* {Name,Node}, if the supervisor is locally registered at  an-
		  other	node

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

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

	      ChildSpec	must be	a valid	child specification (unless the	super-
	      visor  is	a simple_one_for_one supervisor; see below). The child
	      process is started by using the start function as	defined	in the
	      child specification.

	      For a simple_one_for_one supervisor, the child specification de-
	      fined in Module:init/1 is	used, and ChildSpec must instead be an
	      arbitrary	 list of terms List. The child process is then started
	      by appending List	to the existing	start function arguments, that
	      is,  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 spec-
		  ified	 identifier,  ChildSpec	is discarded, and the function
		  returns     {error,already_present}	   or	   {error,{al-
		  ready_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 are 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 (unless the
		  supervisor is	a simple_one_for_one supervisor,  see  below),
		  the  pid  is	set  to	 undefined,  and  the function returns
		  {ok,undefined}.

	      For a simple_one_for_one supervisor, when	a child	process	 start
	      function	returns	 ignore,  the functions	returns	{ok,undefined}
	      and no child is added to the supervisor.

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

       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()} |
		     {via, Module :: module(), Name :: any()}

	      Creates a	supervisor process as part of a	supervision tree.  For
	      example,	the  function ensures 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 intensity, and child
	      processes.  To  ensure   a   synchronized	  startup   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  lo-
		  cally	as Name	using register/2.

		* If SupName={global,Name}, the	supervisor is registered glob-
		  ally 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 must	export the functions register_name/2, unregis-
		  ter_name/1,  and  send/2,  which must	behave like the	corre-
		  sponding 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	any  term  that	 is  passed  as	 the  argument to Mod-
	      ule:init/1.

		* If the supervisor and	its child processes  are  successfully
		  created  (that  is, if all child process start functions re-
		  turn {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 Sup-
		  Name,	the  function  returns	{error,{already_started,Pid}},
		  where	Pid is the pid of that process.

		* If  Module:init/1  returns ignore, this function returns ig-
		  nore as well,	and the	supervisor terminates with reason nor-
		  mal.

		* If  Module:init/1  fails or returns an incorrect value, this
		  function returns {error,Term}, where Term is a term with in-
		  formation  about  the	 error,	 and the supervisor terminates
		  with reason Term.

		* If any child process start function fails or returns an  er-
		  ror tuple or an erroneous value, the supervisor first	termi-
		  nates	all already started child processes with reason	 shut-
		  down	and  then  terminate itself and	returns	{error,	{shut-
		  down,	Reason}}.

       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 supervisor SupRef to terminate the specified child.

	      If the supervisor	is not	simple_one_for_one,  Id	 must  be  the
	      child  specification  identifier.	The process, if	any, is	termi-
	      nated and, unless	it is a	temporary child, the child  specifica-
	      tion  is	kept by	the supervisor.	The child process can 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  cannot  be  used  for	 these
	      children.

	      If the supervisor	is simple_one_for_one, Id must be the pid() of
	      the child	process. If the	specified process is alive, but	is not
	      a	 child	of the specified supervisor, the function returns {er-
	      ror,not_found}. If the child specification identifier is	speci-
	      fied  instead  of	 a  pid(),  the	 function  returns {error,sim-
	      ple_one_for_one}.

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

	      For a description	of SupRef, see start_child/2.

       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  supervisor
	      SupRef.

	      Notice that calling this function	when  supervising  many	 chil-
	      drens under low memory conditions	can cause an out of memory ex-
	      ception.

	      For a description	of SupRef, see start_child/2.

	      The following information	is given  for  each  child  specifica-
	      tion/process:

		* Id  -	As defined in the child	specification or undefined for
		  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 unde-
		  fined	if there is no such process.

		* Type - As defined in the child specification.

		* Modules - As defined in the child specification.

CALLBACK FUNCTIONS
       The following function must be exported from a supervisor callback mod-
       ule.

EXPORTS
       Module:init(Args) -> Result

	      Types:

		 Args =	term()
		 Result	= {ok,{SupFlags,[ChildSpec]}} |	ignore
		  SupFlags = sup_flags()
		  ChildSpec = child_spec()

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

	      Args is the Args argument	provided to the	start function.

	      SupFlags	is  the	supervisor flags defining the restart strategy
	      and maximum restart intensity for	the supervisor.	[ChildSpec] is
	      a	 list  of valid	child specifications defining which child pro-
	      cesses the supervisor must start and monitor. See	the discussion
	      in section Supervision Principles	earlier.

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

	      The function can also return ignore.

	      Notice that this function	can also be called as a	part of	a code
	      upgrade  procedure.  Therefore,  the function is not to have any
	      side effects. For	more information about code upgrade of	super-
	      visors,  see section Changing a Supervisor in OTP	Design Princi-
	      ples.

SEE ALSO
       gen_event(3), gen_statem(3), gen_server(3), sys(3)

Ericsson AB			  stdlib 3.8			 supervisor(3)

NAME | DESCRIPTION | SUPERVISION PRINCIPLES | DATA TYPES | EXPORTS | CALLBACK FUNCTIONS | EXPORTS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=supervisor&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help