Actor API

YAActL

Yet Another Actor Library (in Julia VERSION ≥ v"1.3").

The current stable, registered version is installed with

pkg> add YAActL

The development version is installed with:

pkg> add("https://github.com/pbayer/YAActL.jl")

Gives the package version.

Actor([lp::LinkParams], bhv::Function, args1...; kwargs...)
Actor(pid::Int, bhv::Function, args1...; kwargs...)

Create a new actor. Start a task listening to messages msg sent over the returned self and executing bhv(args1..., msg; kwargs...) for each message. The actor stops if sent Stop().

Arguments

• [lp::LinkParams]: parameters for creating the actor,
• pid::Int: process pid to create the actor on, this can also be given with lp,
• bhv: a function implementing the actor's behavior,
• args1...: first arguments to bhv (without possible msg arguments),
• kwargs...: keyword arguments to bhv.

Returns

• a Link to a created actor.

see also: LinkParams

Example

julia> using YAActL, .Threads

julia> act1 = Actor(threadid)               # start an actor who gives its threadid
Channel{Message}(sz_max:32,sz_curr:0)

julia> call!(act1)                          # call it
1

Link{C}(chn::C, pid::Int, type::Symbol)

A mailbox for communicating with actors.

Fields/Parameters

• chn::C:
• pid::Int:
• type::Symbol:

islocal(lk::Link)
islocal(name::Symbol)

Returns true if the actor lk or name has the same pid as the caller, else false.

User remote channel for interacting with actors.

LinkParams(pid=myid(), size=32; taskref=nothing, spawn=false)

Parameters for setting up an Actor.

• pid::Int: process identification,
• size::Int: channel buffer size, must be size ≥ 10,
• taskref::Union{Nothing, Ref{Task}}: If you need a reference to the created task, pass a Ref{Task} object via the keyword argument taskref.
• spawn::Bool: If spawn = true, the Task created may be scheduled on another thread in parallel, equivalent to creating a task via Threads.@spawn.

parallel(size=32; taskref=nothing)

Return LinkParams with spawn=true.

Example

julia> using YAActL, .Threads

julia> myactor = Actor(parallel(), threadid);

julia> call!(myactor)
2

Abstract type for messages to actors.

Response(y, from::Link=self())

A Message representing a response to requests.

Fields

• y: response content,
• from::Link: sender link.

Request(x, from::Link)

A generic Message for user requests.

Timeout()

A return value to signal that a timeout has occurred.

send!(lk::Link, m::Message)
send!(name::Symbol, m::Message)

Send a message m to an actor lk or name (if registered).

receive!(lk; timeout=5.0)
receive!(lk, from; timeout=5.0)
receive!(lk, Msg; timeout=5.0)
receive!(lk, Msg, from; timeout=5.0)

Receive a message over a link lk.

If Msg or from are provided, receive! returns only a matching message. Other messages in lk are restored to it in their previous order.

Parameters

• lk::Link: local or remote link over which the message is received,
• Msg::Type{<:Message}: Message type,
• from::Link: local or remote link of sender. If from is provided, only messages with a from field can be matched.
• timeout::Real=5.0: maximum waiting time in seconds.
  • If timeout==0, lk is scanned only for existing messages.
  • Set timeout=Inf if you don't want to timeout.

Returns

• received message or Timeout().

Dispatch

Depending on its Dispatch mode an actor composes the arguments to the behavior function:

• full: from the Become args... and the msg.x.... This is the default dispatch mode.
• state: from the actor state and the msg.x.... In this case the actor updates its state with the result of the behavior function. The result is saved in a Tuple.

become!(lk::Link, bhv::Function, args1...; kwargs...)
become!(name::Symbol, ....)

Cause an actor to change behavior.

Arguments

• actor lk::Link (or name::Symbol if registered),
• bhv: function implementing the new behavior,
• args1...: first arguments to bhv (without a possible msg argument),
• kwargs...: keyword arguments to bhv.

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

Cast a message 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!.

exit!(lk::Link, code=0)
exit!(name::Symbol, code=0)

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

set!(lk::Link, dsp::Dispatch)
set!(name::Symbol, dsp::Dispatch)

Set the lk actor's Dispatch to dsp.

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

• an actor lk::Link or name::Symbol (if registered),
• x: value/variable to update the choosen state with,
• arg::Args: arguments to update,
• s::Symbol: can be one of :sta, :dsp, :arg, :self, :name.

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)       # note that fact is in state dispatch
YAActL.Update{Int64}(:sta, 5)

julia> call!(fact, 5)         # call it with 5
10

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

julia> call!(fact, 5)         # add the last result, 5 and u=5
20

become(bhv::Function, args...; kwargs...)

Cause your actor to take on a new behavior. This can only be called from inside an actor/behavior.

Arguments

• bhv::Function: function implementing the new behavior,
• args...: arguments to bhv (without msg),
• kwargs...: keyword arguments to bhv.

self()

Get the Link of your actor.

stop(code=0)

Cause your actor to exit with code.

request!(lk::Link, msg::Message; full=false, timeout::Real=5.0)
request!(lk::Link, Msg::Type{<:Message}, args...; kwargs...)
request!(name::Symbol, args...; kwargs...)

Send a message to an actor, block, receive and return the result.

Arguments

• lk::Link: actor link, or name::Symbol (if registered),
• msg::Message: a message,
• Msg::Type{<:Message}: a message type,
• args...: optional arguments to Msg,
• full: if true return the full Response message.
• timeout::Real=5.0: timeout in seconds after which a Timeout is returned,
• kwargs...: full or timeout.

call!(lk::Link, from::Link, args2...)
call!(lk::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; If from is omitted, call! blocks and returns the result.
• args2...: second arguments to the actor.
• timeout::Real=5.0: timeout in seconds.

exec!(lk::Link, from::Link, f::Function, args...; kwargs...)
exec!(lk::Link, from::Link, fu::Func)
exec!(lk::Link, fu::Func; timeout::Real=5.0)
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

• lk::Link or name::Symbol of the actor,
• from::Link: the link a Response should be sent to. If from is ommitted, exec! blocks, waits and returns the result. In that case there is a timeout.
• f::Function, args...; kwargs... or
• fu::Func: function arguments,
• timeout::Real=5.0: timeout in seconds. Set timeout=Inf if you don't want a timeout.

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

Ask the lk actor to send a Response message to from with an internal state variable s.

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

• s::Symbol can be one of :sta, :res, :bhv, :dsp.

Examples

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

julia> fact = Actor(f, 1)     # start an actor with it
Channel{Message}(sz_max:32,sz_curr:0)

julia> cast!(fact, 1)         # cast a second parameter to it
YAActL.Cast{Tuple{Int64}}((1,))

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

julia> query!(fact, :bhv)     # query the behavior
f (generic function with 1 method)

julia> set!(fact, state)      # set dispatch mode
YAActL.Update{Dispatch}(:dsp, state)

julia> query!(fact, :dsp)     # query the dispatch mode
state::Dispatch = 1

julia> update!(fact, 10)      # update the state
YAActL.Update{Int64}(:sta, 10)

julia> query!(fact)           # query the state variable
10

julia> call!(fact, 1)
11

register(name::Symbol, lk::Link)

Register the actor lk with name. Returns true if the registration succeeds, false if name is already in use.

unregister(name::Symbol)

Remove any registrations associated with name.

whereis(name::Symbol)

Find out whether name is registered. Return the actor link lk or missing if not found.

registered()

Return an Array of all registered actors in the system.

init!(lk::Link, f::Function, args...; kwargs...)
init!(name::Symbol, ....)

Tell an actor lk to save the function f with the given arguments as an init function, to execute it and to save the returned value as state sta variable.

The init function will be called at actor restart.

term!(lk::Link, f::Function, args1...; kwargs...)
term!(name::Symbol, ....)

Tell an actor lk to execute a function f with the given arguments when it terminates. f must accept a code=0 as last argument. This is added by the actor to args1... when it exit!s.