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
— Functioncall(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
(orname::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
Actors.cast
— Functioncast(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
.
Actors.exec
— Functionexec(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
orname::Symbol
if registered, from::Link
: the link aResponse
should be sent to.f
: a callable object,args...; kwargs...
: arguments and keyword arguments to it,timeout::Real=5.0
: timeout in seconds. Settimeout=Inf
if you don't want to timeout.
Note: If from
is ommitted, exec
blocks, waits and returns the result (with a timeout
).
Actors.exit!
— Functionexit!(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.
Actors.info
— Functioninfo(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.
Actors.init!
— Functioninit!(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
orname::Symbol
if registered, f
: callable object,args...
: arguments tof
,kwargs...
: keyword arguments tof
.
Actors.query
— Functionquery(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
orname::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,)))
Actors.term!
— Functionterm!(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.
Actors.update!
— Functionupdate!(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
orname::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
Types
The following is needed for updating arguments:
Actors.Args
— TypeArgs(args...; kwargs...)
A structure for updating arguments to an actor's behavior.