From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/stdlib/doc/src/supervisor.xml | 495 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 495 insertions(+) create mode 100644 lib/stdlib/doc/src/supervisor.xml (limited to 'lib/stdlib/doc/src/supervisor.xml') diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml new file mode 100644 index 0000000000..adf9d24eae --- /dev/null +++ b/lib/stdlib/doc/src/supervisor.xml @@ -0,0 +1,495 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + supervisor + + + + +
+ supervisor + Generic Supervisor Behaviour + +

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 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 specified 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 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 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 time, + 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 processes 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 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.

+ + +
+ + + start_link(Module, Args) -> Result + start_link(SupName, Module, Args) -> Result + Create a supervisor process. + + 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 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 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 function returns + {error,shutdown} and the supervisor terminates all + started child processes and then itself with reason + shutdown.

+ + + + start_child(SupRef, ChildSpec) -> Result + Dynamically add a child process to a supervisor. + + 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 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 + Terminate a child process belonging to a supervisor. + + 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 + Delete a child specification from a supervisor. + + 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 + 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, 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 + Restart a terminated child process belonging to a supervisor. + + 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 corresponding 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 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}] + Return information about all children specifications and child processes belonging to a supervisor. + + 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 list with information about all child + specifications and child processes belonging to + the supervisor SupRef.

+

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, or undefined if there is no such process.

+ + +

Type - as defined in the child specification.

+ + +

Modules - as defined in the child specification.

+ + + + + + check_childspecs([ChildSpec]) -> Result + Check if children specifications are syntactically correct. + + 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.

+
+ + + Module:init(Args) -> Result + Return a supervisor specification. + + Args = term() + Result = {ok,{{RestartStrategy,MaxR,MaxT},[ChildSpec]}} | ignore +  RestartStrategy = one_for_all | one_for_one | rest_for_one | simple_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 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(3), + gen_fsm(3), + gen_server(3), + sys(3)

+
+ + -- cgit v1.2.3