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::SenderIndex;

pub use message::Handler;

pub use message::Message;

pub use message::MessageResponse;

pub use message::MessageResult;

Modules

address

Traits and type definitions for the address of actor model.

cron

Repetitive task execution in an actor.

envelope

Traits and type definitions for the envelope of a message.

errors

Re-exports some error types from tokio.

macros

Utility macros for error reporting and debug tracing.

message

Message passing between actors.

observer

Observer pattern for actors.

supervisor

Supervision for actors.

Structs

Context

The default implementation of an actor context.

Enums

ActorState

State of an actor.

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

Describes an actor.

ActorContext

Describes the execution context of an actor.

Derive Macros

Messagederive

Derive the Message trait for a struct or enum.

MessageResponsederive

Derive the MessageResponse trait for a struct or enum.