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:

strategybrief description
:one_for_oneonly the terminated actor is restarted (default strategy),
:one_for_allall other child actors are shutdown, then all child actors are restarted,
:rest_for_oneactors 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 optionbrief description
:permanentthe child actor is always restarted,
:temporarythe child is never restarted, regardless of the supervision strategy,
:transientthe 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 functionbrief description
supervisorstart a supervisor actor,
superviseadd an actor to a supervisor's child list,
unsupervisedelete an actor or task from a supervisor's child list,
start_actorstart an actor as a child,
start_taskstart a task as a child,
terminate_childterminate a child and to remove it from its child list,
set_strategychange the supervision strategy,
count_childrenreturn a children count,
which_childrenreturn a list of all children.

Functions

Actors.supervisorFunction
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.superviseFunction
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.unsuperviseFunction
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.start_actorFunction
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_taskFunction
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_childrenFunction
count_children(sv)

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

source
Actors.which_childrenFunction
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_childFunction
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