Supervisors

Supervisors allow some automation and control of error handling in an actor system. A supervisor actor can restart its children if they should terminate.

Supervision Strategies

What a supervisor does if one of its children terminates, is determined by its supervision strategy argument:

strategy	brief description
`:one_for_one`	only the terminated actor is restarted (default strategy),
`:one_for_all`	all other child actors are shutdown, then all child actors are restarted,
`:rest_for_one`	actors registered to the supervisor after the terminated one are shutdown, then the terminated one and the rest are restarted.

Child Restart Options

Child restart options with supervise allow for yet finer child-specific control of restarting:

restart option	brief description
`:permanent`	the child actor is always restarted,
`:temporary`	the child is never restarted, regardless of the supervision strategy,
`:transient`	the child is restarted only if it terminates abnormally, i.e., with an exit reason other than `:normal` or `:shutdown`.

Supervision API

Supervisors have the following API:

API function	brief description
`supervisor`	start a supervisor actor,
`supervise`	add an actor to a supervisor's child list,
`unsupervise`	delete an actor or task from a supervisor's child list,
`start_actor`	start an actor as a child,
`start_task`	start a task as a child,
`terminate_child`	terminate a child and to remove it from its child list,
`set_strategy`	change the supervision strategy,
`count_children`	return a children count,
`which_children`	return a list of all children.

Functions

Actors.supervisor — Function

supervisor( strategy=:one_for_one, 
            max_restarts::Int=3, 
            max_seconds::Real=5; 
            name=nothing, kwargs...)

Spawn a supervisor actor with an empty child list and return a link to it.

Arguments

The following arguments are mandatory and go into a supervisor's options:

strategy=:one_for_one: supervision strategy, can be either :one_for_one, :one_for_all or :rest_for_one,
max_restarts::Int=3: maximum number of restarts allowed in a time frame,
max_seconds::Real=5: time frame in which max_restarts applies,

Keyword arguments and further options

name=nothing: name (Symbol) under which a supervisor should be registered, if nothing it doesn't get registered,
kwargs...: further keyword arguments to the Supervisor and to spawn. Keyword arguments not taken by spawn are supervisor options, used to extend a supervisor's functionality.

Reserved options

strategy, max_restarts, max_seconds, name are reserved, see above,
spares=[5,6,7]: spare pids, where you can give spare pids (e.g. [5,6,7]) to a supervisor used for actor restarts after node failures.

source

Actors.supervise — Function

supervise(sv, child=self(); cb=nothing, restart::Symbol=:transient)

Tell a supervisor sv to supervise the given child actor.

Arguments

sv: link or registered name of a supervisor,
child: link or registered name of an actor to supervise.

Keyword Arguments

cb=nothing: callback (a callable object), takes the previous actor behavior as argument and must return a Link to a new actor; if nothing, the actor gets restarted with its init! callback or its previous behavior.
restart::Symbol=:transient: restart option, one of :permanent, :temporary, :transient,

source

Actors.unsupervise — Function

unsupervise(sv, lst=self())

Tell a supervisor sv to delete ls from its childs list.

Arguments

sv: link or registered name of a supervisor,
lst: link, registered name of an actor or task.

source

Actors.set_strategy — Function

set_strategy(sv, strategy::Symbol)

Tell a supervisor sv to change its restart strategy.

source

Actors.start_actor — Function

start_actor(start, sv, cb=nothing, restart::Symbol=:transient; 
            name::Union{Symbol,Nothing}=nothing, kwargs...)

Tell a supervisor sv to start an actor, to add it to its childs list and to return a link to it.

Arguments

start: start behavior of the child, a callable object,
sv::Link: link to a started supervisor,
cb=nothing: callback (a callable object, gets the last actor behavior as argument and must return a Link); if nothing, the actor gets restarted with its init! callback or with its last behavior,
restart::Symbol=:transient: restart option, one of :permanent, :temporary, :transient,
name::Union{Symbol,Nothing}=nothing, name (Symbol) under which the actor should be registered,
kwargs...: keyword arguments to spawn.

source

Actors.start_task — Function

start_task(start, sv, cb=nothing; 
           timeout::Real=5.0, pollint::Real=0.1)

Spawn a task with a start behavior and tell the supervisor sv to supervise it (with restart strategy :transient) and return a reference to it.

Parameters

start: must be a callable object (with no arguments),
sv: link or registered name of a supervisor,
cb=nothing: callback for restart (a callable object, must return a Task); if cb=nothing, the task gets restarted with its start function,
timeout::Real=5.0: how long [seconds] should the task be supervised,
pollint::Real=0.1: polling interval [seconds].

source

Actors.count_children — Function

count_children(sv)

Return a named tuple containing children counts for the given supervisor sv (link or registered name).

source

Actors.which_children — Function

which_children(sv, info=false)

Tell a supervisor sv to return its childs list.

Arguments

sv: link or registered name of a supervisor,
info=false: If info=true, return a list of named tuples with child information.

source

Actors.terminate_child — Function

terminate_child(sv, ls)

Tell a supervisor sv to remove a child ls from its childs list and to terminate it with reason :shutdown.

Arguments

sv: link or registered name of a supervisor,
ls: link or registered name of a child.

source