Crate acktor 

A pure-Rust actor framework built on top of the Tokio async runtime, inspired by Alice Ryhl’s Actors with Tokio.

acktor builds on the patterns described in Alice Ryhl’s blog post and extends them into a structured library. Each actor runs as an independent tokio task with its own mailbox, processing messages one at a time. Actors communicate exclusively through message passing — there is no shared mutable state. The framework provides lifecycle hooks, supervision, an observer pattern, and support for periodic tasks.

Quick Start

An example Counter actor that handles arithmetic messages might be the following:

use acktor::{Actor, Context, Handler, Message, Signal};

#[derive(Debug)]
struct Counter(i64);

impl Actor for Counter {
    type Context = Context<Self>;
    type Error = String;
}

#[derive(Debug, Message)]
#[result_type(i64)]
enum CounterMsg {
    Increment,
    Get,
}

impl Handler<CounterMsg> for Counter {
    type Result = i64;

    async fn handle(&mut self, msg: CounterMsg, _ctx: &mut Self::Context) -> i64 {
        match msg {
            CounterMsg::Increment => self.0 += 1,
            CounterMsg::Get => {}
        }
        self.0
    }
}

async fn run() {
    let (addr, handle) = Counter(0).run("counter").unwrap();

    // fire-and-forget
    addr.do_send(CounterMsg::Increment).await.unwrap();

    // request-reply
    let result = addr.send(CounterMsg::Get).await.unwrap().await.unwrap();
    println!("Counter: {result}"); // Counter: 1

    addr.do_send(Signal::Stop).await.unwrap();
    handle.await.unwrap();
}

Feature Flags

Feature	Default	Description
derive	Yes	Enables #[derive(Message)] and #[derive(MessageResponse)] macros.
tokio-tracing	No	Names spawned actor tasks for tokio-console. Requires building with RUSTFLAGS="--cfg tokio_unstable".
bottleneck-warning	No	Emits tracing::debug! logs when an observer’s mailbox is full during notification, useful for spotting slow consumers.

Re-exports

pub use address::Address;

pub use address::Recipient;

pub use address::Sender;

pub use address::SenderId;

pub use message::Handler;

pub use message::Message;

pub use message::MessageResponse;

Modules

address

Traits and type definitions for the address of actor model.

channel

Channel primitives used by this crate, wrapping tokio’s channels so receive operations yield this crate’s RecvError.

croncron

Repetitive task execution in an actor.

envelope

Traits and type definitions for the envelope of a message.

message

Message passing between actors.

observerobserver

Observer pattern for actors.

supervisor

Supervision for actors.

utils

Structs

Context

The default implementation of an actor context.

JoinHandle

An owned permission to join on a task (await its termination).

Enums

ActorState

State of an actor.

RecvError

Error returned when receiving a message.

SendError

Error returned when sending a message.

Signal

A message which is used to stop/terminate an actor.

Stopping

Return value of Actor::stopping.

Constants

DEFAULT_MAILBOX_CAPACITY

The default mailbox capacity for actors.

Traits

Actor

An actor.

ActorContext

The execution context of an actor.

ErrorReport

A trait which allows an error to print itself and its sources (if any) recursively.

Type Aliases

ActorId

Actor index type.

BoxError

Alias for a type-erased error type.

Derive Macros

Messagederive

Derive the Message trait for a struct or enum.

MessageResponsederive

Derive the MessageResponse trait for a struct or enum.