From de1d77d0b4e8ab9e507addf7878457202357ca32 Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Mon, 20 Oct 2014 16:59:10 +0200 Subject: Add documentation of maps in supervisor flags and child specs --- system/doc/design_principles/appup_cookbook.xml | 6 +- system/doc/design_principles/sup_princ.xml | 233 ++++++++++++++++-------- 2 files changed, 163 insertions(+), 76 deletions(-) (limited to 'system/doc/design_principles') diff --git a/system/doc/design_principles/appup_cookbook.xml b/system/doc/design_principles/appup_cookbook.xml index 70c34a5a06..45f144e8b7 100644 --- a/system/doc/design_principles/appup_cookbook.xml +++ b/system/doc/design_principles/appup_cookbook.xml @@ -4,7 +4,7 @@
- 20032013 + 20032014 Ericsson AB. All Rights Reserved. @@ -239,7 +239,7 @@ system_code_change(Chs, _Module, _OldVsn, _Extra) -> Changing a Supervisor

The supervisor behaviour supports changing the internal state, - i.e. changing restart strategy and maximum restart frequency + i.e. changing restart strategy and maximum restart intensity properties, as well as changing existing child specifications.

Adding and deleting child processes are also possible, but not handled automatically. Instructions must be given by in @@ -267,7 +267,7 @@ system_code_change(Chs, _Module, _OldVsn, _Extra) -> ... init(_Args) -> - {ok, {{one_for_all, 1, 60}, ...}}. + {ok, {#{strategy => one_for_all, ...}, ...}}.

The file ch_app.appup:

{"2", diff --git a/system/doc/design_principles/sup_princ.xml b/system/doc/design_principles/sup_princ.xml index 11ef3813d6..3d7b53e339 100644 --- a/system/doc/design_principles/sup_princ.xml +++ b/system/doc/design_principles/sup_princ.xml @@ -4,7 +4,7 @@
- 19972013 + 19972014 Ericsson AB. All Rights Reserved. @@ -29,14 +29,14 @@ sup_princ.xml

This section should be read in conjunction with - supervisor(3), where all details about the supervisor - behaviour is given.

+ supervisor(3), where + all details about the supervisor behaviour are described.

Supervision Principles -

A supervisor is responsible for starting, stopping and +

A 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 + that it shall keep its child processes alive by restarting them when necessary.

Which child processes to start and monitor is specified by a list of child specifications. @@ -61,18 +61,59 @@ start_link() -> supervisor:start_link(ch_sup, []). init(_Args) -> - {ok, {{one_for_one, 1, 60}, - [{ch3, {ch3, start_link, []}, - permanent, brutal_kill, worker, [ch3]}]}}. -

one_for_one is the restart strategy.

-

1 and 60 defines the maximum restart frequency.

-

The tuple {ch3, ...} is a child specification.

+ SupFlags = #{strategy => one_for_one, intensity => 1, period => 5}, + ChildSpecs = [#{id => ch3, + start => {ch3, start_link, []}, + restart => permanent, + shutdown => brutal_kill, + type => worker, + modules => [cg3]}], + {ok, {SupFlags, ChildSpecs}}. +

The SupFlags variable in the return value + from init/1 represents + the supervisor flags.

+

The ChildSpecs variable in the return value + from init/1 is a list of child + specifications.

+
+ +
+ Supervisor Flags +

This is the type definition for the supervisor flags:

+ strategy(), % optional + intensity => non_neg_integer(), % optional + period => pos_integer()} % optional + strategy() = one_for_all + | one_for_one + | rest_for_one + | simple_one_for_one]]> + + +

strategy specifies + the restart + strategy.

+ + +

intensity and period specify + the maximum restart + intensity.

+ +
Restart Strategy +

The restart strategy is specified by + the strategy key in the supervisor flags map returned by + the callback function init:

+ +SupFlags = #{strategy => Strategy, ...} +

The strategy key is optional in this map. If it is not + given, it defaults to one_for_one.

+
one_for_one

If a child process terminates, only that process is restarted.

@@ -85,7 +126,7 @@ init(_Args) ->
one_for_all

If a child process terminates, all other child processes are - terminated and then all child processes, including + terminated, and then all child processes, including the terminated one, are restarted.

@@ -100,29 +141,36 @@ init(_Args) -> process in start order -- are terminated. Then the terminated child process and the rest of the child processes are restarted.

+ +
+ simple_one_for_one +

See simple-one-for-one + supervisors.

+
- - Maximum Restart Frequency + + Maximum Restart Intensity

The supervisors have a built-in mechanism to limit the number of restarts which can occur in a given time interval. This is - determined by the values of the two parameters MaxR and - MaxT in the start specification returned by the callback - function init:

+ specified by the two keys intensity and + period in the supervisor flags map returned by the + callback function init:

-init(...) -> - {ok, {{RestartStrategy, MaxR, MaxT}, - [ChildSpec, ...]}}. +SupFlags = #{intensity => MaxR, period => MaxT, ...}

If more than MaxR number of restarts occur in the last - MaxT seconds, then the supervisor terminates all the child + MaxT seconds, the supervisor terminates all the child processes and then itself.

-

When the supervisor terminates, then the next higher level +

When the supervisor terminates, the next higher level supervisor takes some action. It either restarts the terminated - supervisor, or terminates itself.

+ supervisor or terminates itself.

The intention of the restart mechanism is to prevent a situation where a process repeatedly dies for the same reason, only to be restarted again.

+

The keys intensity and period are optional in the + supervisor flags map. If they are not given, they default + to 1 and 5, respectively.

@@ -130,33 +178,42 @@ init(...) -> Child Specification

This is the type definition for a child specification:

0 | infinity - Type = worker | supervisor - Modules = [Module] | dynamic - Module = atom()]]> +child_spec() = #{id => child_id(), % mandatory + start => mfargs(), % mandatory + restart => restart(), % optional + shutdown => shutdown(), % optional + type => worker(), % optional + modules => modules()} % optional + child_id() = term() + mfargs() = {M :: module(), F :: atom(), A :: [term()]} + modules() = [module()] | dynamic + restart() = permanent | transient | temporary + shutdown() = brutal_kill | timeout() + worker() = worker | supervisor]]> -

Id is a name that is used to identify the child +

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

+

The id key is mandatory.

+

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

 -

StartFunc defines the function call used to start +

start defines the function call used to start the child process. It is a module-function-arguments tuple used as apply(M, F, A).

It should be (or result in) a call to supervisor:start_link, gen_server:start_link, - gen_fsm:start_link or gen_event:start_link. + gen_fsm:start_link, or gen_event:start_link. (Or a function compliant with these functions, see supervisor(3) for details.

+

The start key is mandatory.

 -

Restart defines when a terminated child process should +

restart defines when a terminated child process shall be restarted.

A permanent child process is always restarted. @@ -166,12 +223,14 @@ init(...) -> death causes the temporary process to be terminated). A transient child process is restarted only if it terminates abnormally, i.e. with another exit reason than - normal, shutdown or {shutdown,Term}. + normal, shutdown, or {shutdown,Term}. +

The restart key is optional. If it is not given, the + default value permanent will be used.

-

Shutdown defines how a child process should be +

shutdown defines how a child process shall be terminated.

brutal_kill means the child process is @@ -184,58 +243,78 @@ init(...) -> terminated using exit(Child, kill). If the child process is another supervisor, it should be set to infinity to give the subtree enough time to - shutdown. It is also allowed to set it to infinity, if the - child process is a worker. + shut down. It is also allowed to set it to infinity, + if the child process is a worker. -

Be careful by setting the Shutdown strategy to +

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 implemented in a safe way and its cleanup procedure must always return.

 +

The shutdown key is optional. If it is not given, + and the child is of type worker, the default value + 5000 will be used; if the child is of type + supervisor, the default value infinity will be + used.

-

Type specifies if the child process is a supervisor or +

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

+

The type key is optional. If it is not given, the + default value worker will be used.

 -

Modules should be a list with one element +

modules should be a list with one element [Module], where Module is the name of the callback module, if the child process is a supervisor, gen_server or gen_fsm. If the child process is a gen_event, - Modules should be dynamic.

+ the value shall be dynamic.

This information is used by the release handler during upgrades and downgrades, see Release Handling.

+

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

Example: The child specification to start the server ch3 in the example above looks like:

-{ch3, - {ch3, start_link, []}, - permanent, brutal_kill, worker, [ch3]} +#{id => ch3, + start => {ch3, start_link, []}, + restart => permanent, + shutdown => brutal_kill, + type => worker, + modules => [ch3]} +

or simplified, relying on the default values:

+ +#{id => ch3, + start => {ch3, start_link, []} + shutdown => brutal_kill}

Example: A child specification to start the event manager from the chapter about gen_event:

-{error_man, - {gen_event, start_link, [{local, error_man}]}, - permanent, 5000, worker, dynamic} -

Both the server and event manager are registered processes which +#{id => error_man, + start => {gen_event, start_link, [{local, error_man}]}, + modules => dynamic} +

Both server and event manager are registered processes which can be expected to be accessible at all times, thus they are specified to be permanent.

ch3 does not need to do any cleaning up before termination, thus no shutdown time is needed but brutal_kill should be sufficient. error_man may need some time for the event handlers to clean up, thus - Shutdown is set to 5000 ms.

+ the shutdown time is set to 5000 ms (which is the default + value).

Example: A child specification to start another supervisor:

-{sup, - {sup, start_link, []}, - transient, infinity, supervisor, [sup]} +#{id => sup, + start => {sup, start_link, []}, + restart => transient, + type => supervisor} % will cause default shutdown=>infinity
@@ -262,16 +341,18 @@ start_link() -> supervisor:start_link({local, Name}, Module, Args) or supervisor:start_link({global, Name}, Module, Args).

The new supervisor process calls the callback function - ch_sup:init([]). init is expected to return - {ok, StartSpec}:

+ ch_sup:init([]). init shall return + {ok, {SupFlags, ChildSpecs}}:

init(_Args) -> - {ok, {{one_for_one, 1, 60}, - [{ch3, {ch3, start_link, []}, - permanent, brutal_kill, worker, [ch3]}]}}. + SupFlags = #{}, + ChildSpecs = [#{id => ch3, + start => {ch3, start_link, []}, + shutdown => brutal_kill}], + {ok, {SupFlags, ChildSpecs}}.

The supervisor then starts all its child processes according to - the child specifications in the start specification. In this case - there is one child process, ch3.

+ the given child specifications. In this case there, is one child + process, ch3.

Note that supervisor:start_link is synchronous. It does not return until all child processes have been started.

@@ -303,17 +384,19 @@ supervisor:terminate_child(Sup, Id) supervisor:delete_child(Sup, Id)

Sup is the pid, or name, of the supervisor. - Id is the id specified in the child specification.

+ Id is the value associated with the id key in + the child specification.

As with dynamically added child processes, the effects of deleting a static child process is lost if the supervisor itself restarts.

+
Simple-One-For-One Supervisors

A supervisor with restart strategy simple_one_for_one is a simplified one_for_one supervisor, where all child processes are - dynamically added instances of the same process.

+ dynamically added instances of the same child specification.

Example of a callback module for a simple_one_for_one supervisor:

-module(simple_sup). @@ -326,9 +409,13 @@ start_link() -> supervisor:start_link(simple_sup, []). init(_Args) -> - {ok, {{simple_one_for_one, 0, 1}, - [{call, {call, start_link, []}, - temporary, brutal_kill, worker, [call]}]}}. + SupFlags = #{strategy => simple_one_for_one, + intensity => 0, + period => 1}, + ChildSpecs = [#{id => call, + start => {call, start_link, []}, + shutdown => brutal_kill}], + {ok, {SupFlags, ChildSpecs}}.

When started, the supervisor will not start any child processes. Instead, all child processes are added dynamically by calling:

@@ -336,7 +423,7 @@ supervisor:start_child(Sup, List)

Sup is the pid, or name, of the supervisor. List is an arbitrary list of terms which will be added to the list of arguments specified in the child specification. If - the start function is specified as {M, F, A}, then + the start function is specified as {M, F, A}, the child process is started by calling apply(M, F, A++List).

For example, adding a child to simple_sup above:

@@ -352,10 +439,10 @@ call:start_link(id1) supervisor:terminate_child(Sup, Pid)

where Sup is the pid, or name, of the supervisor and Pid is the pid of the child.

-

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.

+

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

-- cgit v1.2.3