std::actors
State one task owns, changed by the messages it receives: the tour’s
counter server as a helper. Actor.start(supervisor, state, handle)
starts a task under the supervisor that folds each message into its
state with handle, one message at a time, so nothing else touches the
state and no locks are needed. Its inbox holds 64 messages unless the
call gives another size (inbox: 256).
Actor.cast sends a message and returns at once. Actor.call sends a
message that carries a Reply, which the handler replies to with
Reply.send, and waits for the reply up to a timeout, five seconds
unless the call gives another (timeout: Duration.seconds(1)). A message type
is an enum, and a variant that expects a reply holds the Reply for
it, so each kind of call has its own reply type:
enum Counter Add Int Get {reply: Reply<Int>} end counter = Actor.start(App.workers, 0, fn count, message -> case message .Add(n) -> count + n .Get{reply:} -> Reply.send(reply, count) count end end) _ = Actor.cast(counter, .Add(2)) n = Actor.call(counter, fn reply -> .Get{reply:})?
Messages are handled in the order they are sent. A handler that traps
stops the task, and the supervisor’s restart rule decides whether it
starts again, from the initial state. Actor.stop closes the inbox: the
task handles what is already queued and ends. Start an actor you stop
under a Restart.Transient supervisor, which restarts it after a
failure and lets a stop end it; Restart.Permanent would start it again
on its closed inbox.
Import with import std::actors.
Exports
Section titled “Exports”struct Actor
Section titled “struct Actor”struct Actor<M>
opaque — construction surface is private to its defining module
A running actor that takes messages of type M.
Actor.start
Section titled “Actor.start”fn start<S>(supervisor: Supervisor, state: S, inbox: PositiveInt = 64, handle: (S, M) -> S) -> Actor<M>
type function on Actor
Starts a task under supervisor that holds state and folds each
message into it with handle, whose result is the next state. The
inbox holds inbox messages, 64 unless the call says otherwise; a
cast or call waits while it is full. Called during boot, where a
program builds its supervisors.
Actor.cast
Section titled “Actor.cast”fn cast(actor: Actor<M>, message: M) -> Result<Unit, CallError>
type function on Actor
Sends message and returns once it is queued; Err(Stopped) when
the actor has stopped.
Actor.call
Section titled “Actor.call”fn call<R>(actor: Actor<M>, timeout: Duration = Duration.seconds(5), message: (Reply<R>) -> M) -> Result<R, CallError>
type function on Actor
Sends the message message builds around a fresh Reply, and waits
up to timeout, five seconds unless the call says otherwise, for the
handler’s Reply.send: Err(TimedOut) when no reply comes in time,
Err(Stopped) when the actor has stopped.
Actor.stop
Section titled “Actor.stop”fn stop(actor: Actor<M>) -> Unit
type function on Actor
Closes the actor’s inbox. The task handles the messages already
queued and ends; a later cast or call returns Err(Stopped).
Actor.inspect
Section titled “Actor.inspect”impl Debug for Actor<M>
fn inspect<M>(value: Actor<M>) -> String where M: Debug
impl Debug.inspect
struct Reply
Section titled “struct Reply”struct Reply<R>
opaque — construction surface is private to its defining module
The way back to a caller waiting in Actor.call: the handler answers
it with Reply.send.
Reply.send
Section titled “Reply.send”fn send(reply: Reply<R>, value: R) -> Unit
type function on Reply
Replies to the caller waiting on reply. A reply to a caller that
has stopped waiting is dropped.
Reply.inspect
Section titled “Reply.inspect”impl Debug for Reply<R>
fn inspect<R>(value: Reply<R>) -> String where R: Debug
impl Debug.inspect
enum CallError
Section titled “enum CallError”enum CallError TimedOut Stopped end
Why a call or cast got no reply.
Variants
-
TimedOutThe reply did not come within the call’s timeout.
-
StoppedThe actor has stopped, so the message was not delivered.
CallError.to_string
Section titled “CallError.to_string”impl Display for CallError
fn to_string(error: CallError) -> String
impl Display.to_string
assert "${CallError.TimedOut}" == "the actor did not answer in time"
CallError.inspect
Section titled “CallError.inspect”impl Debug for CallError
fn inspect(value: CallError) -> String
impl Debug.inspect
CallError.equal
Section titled “CallError.equal”impl Equatable for CallError
fn equal(a: CallError, b: CallError) -> Bool
impl Equatable.equal