From 229d0d8ca88bc344bed89e46541b325c1d267996 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 15:58:09 +0200 Subject: r Use Erlang specs and types for documentation --- lib/stdlib/doc/src/supervisor.xml | 218 ++++++++++++++++++-------------------- 1 file changed, 102 insertions(+), 116 deletions(-) (limited to 'lib/stdlib/doc/src/supervisor.xml') diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml index d6203bdaa0..009aa60faa 100644 --- a/lib/stdlib/doc/src/supervisor.xml +++ b/lib/stdlib/doc/src/supervisor.xml @@ -199,51 +199,81 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} + + + + + + +

Not a pid().

 + + + + + + +

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

+ + + + + + + + + + + + + + + + + + + + + - 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 +

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 + Module:init/1 has returned and all child processes have been started.

-

If SupName={local,Name} the supervisor is registered +

If SupName={local,Name} the supervisor is registered locally as Name using register/2. If - SupName={global,Name} the supervisor is registered + 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.

+

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 + 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 +

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, + 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.

@@ -255,21 +285,15 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} - 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:

+ SupRef which starts the corresponding child process.

+

SupRef can be:

the pid, Name, if the supervisor is locally registered, @@ -278,26 +302,26 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} {global,Name}, if the supervisor is globally registered. -

ChildSpec should be a valid child specification +

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 + 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 + 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 specified Id, ChildSpec is discarded and the function returns {error,already_present} or - {error,{already_started,Child}}, depending on if + {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 +

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, @@ -312,27 +336,20 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} - terminate_child(SupRef, Id) -> Result + Terminate a child process belonging to a supervisor. - - SupRef = Name | {Name,Node} | {global,Name} | pid() -  Name = Node = atom() - Id = pid() | term() - Result = ok | {error,Error} -  Error = not_found | simple_one_for_one - -

Tells the supervisor SupRef to terminate the given +

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 + Id must be the child specification identifier. The process, if there is one, is terminated but 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 supervisor is simple_one_for_one, Id +

If the supervisor is simple_one_for_one, Id must be the child process' pid(). I the specified process is alive, but is not a child of the given supervisor, the function will return @@ -340,119 +357,93 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} 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 + no child specification with the specified Id, the function returns {error,not_found}.

See start_child/2 for a description of - SupRef.

+ SupRef.

 - 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 +

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.

+

See start_child/2 for a description of + SupRef.

If successful, the function returns ok. If the child - specification identified by Id exists but + 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 + 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 +

Tells the supervisor SupRef to restart a child process corresponding to the child specification identified by - Id. The child specification must exist and + 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 +

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 +

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 + {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 newly created list with information about all child specifications and child processes belonging to - the supervisor SupRef.

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

+

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 +

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 +

Child - the pid of the corresponding child process, or undefined if there is no such process.

 -

Type - as defined in the child specification.

+

Type - as defined in the child specification.

 -

Modules - as defined in the child specification.

+

Modules - as defined in the child specification.

 - count_children(SupRef) -> PropListOfCounts + Return counts for the number of childspecs, active children, supervisors and workers. - - 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 following elements of the supervisor's @@ -479,17 +470,12 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} - 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.

+ correct, or {error,Error} otherwise.

 @@ -506,9 +492,9 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} 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() +  RestartStrategy = strategy() +  MaxR = MaxT = integer()>=0 +  ChildSpec = child_spec()

Whenever a supervisor is started using -- cgit v1.2.3