Skip to content

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.

struct Actor<M>

opaque — construction surface is private to its defining module

A running actor that takes messages of type M.

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.

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.

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.

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

impl Debug for Actor<M>

fn inspect<M>(value: Actor<M>) -> String where M: Debug

impl Debug.inspect

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.

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.

impl Debug for Reply<R>

fn inspect<R>(value: Reply<R>) -> String where R: Debug

impl Debug.inspect

enum CallError
    TimedOut
    Stopped
end

Why a call or cast got no reply.

Variants

  • TimedOut

    The reply did not come within the call’s timeout.

  • Stopped

    The actor has stopped, so the message was not delivered.

impl Display for CallError

fn to_string(error: CallError) -> String

impl Display.to_string

assert "${CallError.TimedOut}" == "the actor did not answer in time"

impl Debug for CallError

fn inspect(value: CallError) -> String

impl Debug.inspect

impl Equatable for CallError

fn equal(a: CallError, b: CallError) -> Bool

impl Equatable.equal