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
— Functionsupervisor( 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 whichmax_restarts
applies,
Keyword arguments and further options
name=nothing
: name (Symbol) under which a supervisor should be registered, ifnothing
it doesn't get registered,kwargs...
: further keyword arguments to theSupervisor
and tospawn
. Keyword arguments not taken byspawn
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]
: sparepid
s, where you can give spare pids (e.g.[5,6,7]
) to a supervisor used for actor restarts after node failures.
Actors.supervise
— Functionsupervise(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 aLink
to a new actor; ifnothing
, the actor gets restarted with itsinit!
callback or its previous behavior.restart::Symbol=:transient
: restart option, one of:permanent
,:temporary
,:transient
,
Actors.unsupervise
— Functionunsupervise(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.
Actors.set_strategy
— Functionset_strategy(sv, strategy::Symbol)
Tell a supervisor sv
to change its restart strategy
.
Actors.start_actor
— Functionstart_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 aLink
); ifnothing
, the actor gets restarted with itsinit!
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 tospawn
.
Actors.start_task
— Functionstart_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 aTask
); ifcb=nothing
, the task gets restarted with itsstart
function,timeout::Real=5.0
: how long [seconds] should the task be supervised,pollint::Real=0.1
: polling interval [seconds].
Actors.count_children
— Functioncount_children(sv)
Return a named tuple containing children counts for the given supervisor sv
(link or registered name).
Actors.which_children
— Functionwhich_children(sv, info=false)
Tell a supervisor sv
to return its childs list.
Arguments
sv
: link or registered name of a supervisor,info=false
: Ifinfo=true
, return a list of named tuples with child information.
Actors.terminate_child
— Functionterminate_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.