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 function	brief description
`call`	tell an actor to execute its behavior function and to send the result
`exec`	tell an actor to execute a function and to send the result
`query`	tell 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 function	brief description
`become!`	cause an actor to switch its behavior
`cast`	cause 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 function	brief description
`become`	an actor switches its own behavior
`stop`	an actor stops

Functions

Actors.call — Function

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.

Arguments

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

source

Actors.cast — Function

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.

source

Actors.exec — Function

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.

Arguments

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).

source

Actors.exit! — Function

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.

source

Actors.info — Function

info(lk::Link)

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.

source

Actors.init! — Function

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.

Arguments

actor lk::Link or name::Symbol if registered,
f: callable object,
args...: arguments to f,
kwargs...: keyword arguments to f.

source

Actors.query — Function

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

Query an actor about an internal state variable s.

Parameters

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.

Examples

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
:default

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

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

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,)))

source

Actors.term! — Function

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.

source

Actors.update! — Function

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

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

Arguments

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.

Example

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

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

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

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

source

Types

The following is needed for updating arguments:

Actors.Args — Type

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

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

source