API Overview

All the key types, traits, and macros in one place. For complete API documentation, see docs.rs/acton-reactive.

Core Types

ActonApp

The entry point. Its only job is to boot the system and hand you an ActorRuntime.

let mut runtime = ActonApp::launch_async().await;

ActorRuntime

What launch_async() returns. This is where actor creation, the broker, shutdown, and IPC live.

IPC methods require the ipc feature.

Actor Builder

ManagedActor<Idle, T> — configures an actor before spawning.

Handler-registration methods take &mut self and return &mut Self, while start() consumes the builder. So configure first, then start — you can't chain straight through into .start():

let mut builder = runtime.new_actor::<Counter>();
builder
    .mutate_on::<Increment>(handler)
    .act_on::<GetCount>(handler);

let handle = builder.start().await;

ActorHandle

Reference to a running actor.

handle.send(Message).await;
handle.stop().await.ok();

ask and Request

ask sends a request and waits for the reply. A message becomes askable by implementing Request, which names the reply through an associated type:

impl Request for GetCount {
    type Response = Count;
}

let count = handle.ask(GetCount).await?;

Because inboxes are FIFO, a completed ask also proves every message sent to that actor beforehand has been processed. Handlers are unchanged: they answer through the reply envelope, and an actor cannot tell an ask from a send.

ask always finishes, backed by a 30-second DEFAULT_ASK_TIMEOUT. Outcomes come back as AskError, which is #[non_exhaustive]:

Do not ask from inside a mutate_on handler. Mutable handlers are awaited inline on the message loop, so waiting for a reply stops the actor from processing the message that would produce it.

SupervisedChild

A reference to a supervised child that survives its restarts. ActorHandle names one incarnation and goes stale; SupervisedChild reads a status channel its supervisor publishes to.

SupervisionState is Starting, Running, RestartPending, Restarting, Down (will not come back), or Escalated (allowance exhausted).

FlushBroadcasts

A barrier for broadcasts. broadcast completes when the broker has the message, not when subscribers do, and a broadcast carries no reply address for a subscriber to answer.

broker.ask(FlushBroadcasts).await?;   // answers BroadcastsFlushed

The reply cannot arrive until every earlier broadcast is sitting in every subscriber's inbox. That is delivery, not completion: to know a particular subscriber has handled it, ask that subscriber afterwards.

ActorRuntime::shutdown_all flushes the broker before signalling anything, so broadcasting and then shutting down is not a race.

Reply

Builds the future a handler must return.

MessageContext

The second argument every handler receives — the message plus its routing information. Written ctx or envelope in examples.

MessageContext is not exported from the prelude — you don't normally need to name it, since handlers are closures and the type is inferred.

OutboundEnvelope

A message prepared for sending. This is what reply_envelope() and create_envelope() hand you.

Macros

#[acton_actor]

Marks a struct as actor state.

#[acton_actor]
struct Counter {
    count: i32,
}

#[acton_message]

Marks a struct as a message.

#[acton_message]
struct Increment;

#[acton_message(ipc)]  // Enable IPC serialization
struct GetValue;

#[acton_main]

Sets up the async runtime.

#[acton_main]
async fn main() {
    let runtime = ActonApp::launch_async().await;
    // ...
}

Prelude

Import everything:

use acton_reactive::prelude::*;

Note that MessageContext is deliberately not in the prelude; handlers receive it as an inferred closure parameter.