User API

The user API allows you to communicate with actors using the Actors protocol:

Bidirectional Communication

The following functions send a message to an actor causing it to respond:

API functionbrief description
calltell an actor to execute its behavior function and to send the result
exectell an actor to execute a function and to send the result
querytell an actor's to send one of its internal state variables

Those functions support both asynchronous and synchronous communication.

Actor Control (Unidirectional)

Actors can be controlled with the following functions:

API functionbrief description
become!cause an actor to switch its behavior
castcause an actor to execute its behavior function
exit!cause an actor to terminate
init!tell an actor to execute a function at startup
term!tell an actor to execute a function when it terminates
update!update an actor's internal state

Actors can also operate on themselves, or rather they send themselves messages:

API functionbrief description
becomean actor switches its own behavior
stopan actor stops


call(lk::Link, [from::Link,] args2...; timeout::Real=5.0)
call(name::Symbol, ....)

Call an actor to execute its behavior and to send a Response with the result.


  • actor lk::Link (or name::Symbol if registered),
  • from::Link: sender link,
  • args2...: remaining arguments to the actor.
  • timeout::Real=5.0: timeout in seconds.

Note: If from is omitted, call blocks and returns the result

cast(lk::Link, args2...)
cast(name::Symbol, args2...)

Cast args2... to the actor lk (or name if registered) to execute its behavior with args2... without sending a response.

Note: you can prompt the returned value with query.

exec(lk::Link, from::Link, f, args...; kwargs...)
exec(lk::Link, f, args...; timeout::Real=5.0, kwargs...)
exec(name::Symbol, ....)

Ask an actor lk (or name if registered) to execute an arbitrary function and to send the returned value as Response.


  • actor lk::Link or name::Symbol if registered,
  • from::Link: the link a Response should be sent to.
  • f: a callable object,
  • args...; kwargs...: arguments and keyword arguments to it,
  • timeout::Real=5.0: timeout in seconds. Set timeout=Inf if you don't want to timeout.

Note: If from is ommitted, exec blocks, waits and returns the result (with a timeout).

exit!(lk::Link, reason=:normal)
exit!(name::Symbol, ....)

Tell an actor lk (or name if registered) to stop. If it has a term function, it calls that with reason as last argument.


Return the state of an actor associated with lk:

  • Actors.Info if it is runnable,
  • :done if it has finished,
  • else return the failed task.
init!(lk::Link, f, args...; kwargs...)
init!(name::Symbol, ....)

Tell an actor lk to save the callable object f with the given arguments as an init object in its _ACT variable. The init object will be called by a supervisor at actor restart.


  • actor lk::Link or name::Symbol if registered,
  • f: callable object,
  • args...: arguments to f,
  • kwargs...: keyword arguments to f.
query(lk::Link, [from::Link,] s::Symbol; timeout::Real=5.0)
query(name::Symbol, ....)

Query an actor about an internal state variable s.


  • actor lk::Link or name::Symbol if registered,
  • from::Link: sender link,
  • s::Symbol one of :mode,:bhv,:res,:sta,:usr.
  • timeout::Real=5.0:

Note: If from is omitted, query blocks and returns the response. In that case there is a timeout.


julia> f(x, y; u=0, v=0) = x+y+u+v  # implement a behavior
f (generic function with 1 method)

julia> fact = spawn(Bhv(f, 1))     # start an actor with it
Link{Channel{Any}}(Channel{Any}(sz_max:32,sz_curr:0), 1, :default)

julia> query(fact, :mode)           # query the mode

julia> cast(fact, 1)                # cast a 2nd argument to it

julia> query(fact, :res)            # query the result

julia> query(fact, :sta)            # query the state

julia> query(fact, :bhv)            # query the behavior
Bhv(f, (1,), Base.Iterators.Pairs{Union{},Union{},Tuple{},NamedTuple{(),Tuple{}}}(), Actors.var"#2#4"{Base.Iterators.Pairs{Union{},Union{},Tuple{},NamedTuple{(),Tuple{}}},typeof(f),Tuple{Int64}}(Base.Iterators.Pairs{Union{},Union{},Tuple{},NamedTuple{(),Tuple{}}}(), f, (1,)))
term!(lk::Link, f, args1...; kwargs...)
term!(name::Symbol, ....)

Tell an actor lk (or name::Symbol if registered) to execute f with the given partial arguments and an exit reason when it terminates.

The exit reason is added by the actor to args1... when it exits.

update!(lk::Link, x; s::Symbol=:sta)
update!(lk::Link, arg::Args)
update!(name::Symbol, ....)

Update an actor's internal state s with args....


  • actor lk::Link or name::Symbol if registered,
  • x: value/variable to update the choosen state with,
  • arg::Args: arguments to update,
  • s::Symbol: one of :arg, :mode, :name, :self, :sta, :usr.

Note: If you want to update the stored arguments to the behavior function with s=:arg, you must pass an Args to arg. If Args has keyword arguments, they are merged with existing keyword arguments to the behavior function.


julia> update!(fact, 5)       # update the state variable
Actors.Update(:sta, 5)

julia> query(fact, :sta)      # query it

julia> update!(fact, Args(0, u=5, v=5));  # update arguments to the behavior 

julia> call(fact, 0)          # call the actor with 0


The following is needed for updating arguments:

Args(args...; kwargs...)

A structure for updating arguments to an actor's behavior.