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)]
enum CounterMsg {
    Increment,
    Get,
}

impl Message for CounterMsg {
    type Result = i64;
}

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 start() {
    let (addr, handle) = Counter(0).start("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 error::ErrorReport;

pub use error::RecvError;

pub use error::SendError;

pub use stable_type_id::StableId;identifier

pub use stable_type_id::StableTypeId;identifier

pub use actor::Actor;

pub use actor::ActorContext;

pub use actor::ActorId;

pub use actor::ActorState;

pub use actor::Stopping;

pub use actor::RemoteAddressable;ipc

pub use actor::RemoteSpawnable;ipc

pub use address::RemoteProxy;ipc

pub use address::Address;

pub use address::Recipient;

pub use address::Sender;

pub use address::SenderInfo;

pub use message::MessageId;identifier

pub use message::Handler;

pub use message::Message;

pub use message::MessageResponse;

pub use acktor_ipc_proto as proto;ipc

Modules

actor

Traits and type definitions for actors.

address

Traits and type definitions for actor address.

channel

Channel primitives used by this crate.

codecipc

Codec traits for encoding and decoding remote messages.

croncron

Repetitive task execution in an actor.

envelope

Traits and type definitions for the envelope of a message.

error

Error types used by this crate.

message

Message passing between actors.

observerobserver

Observer pattern for actors.

stable_type_ididentifier

Stable type identifier.

supervisor

Supervision for actors.

utils

Utility functions and types used by this crate.

Structs

Context

The default implementation of an actor context.

JoinHandle

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

Enums

Signal

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

Constants

DEFAULT_MAILBOX_CAPACITY

The default mailbox capacity for actors.

Attribute Macros

remotederive and ipc

Attribute macro applies to the impl Actor for MyActor block, which overrides the internal method Actor::remote_mailbox to return a RemoteMailbox for a remote addressable actor.

Derive Macros

Messagederive

Derive the Message trait for a struct or enum.

MessageIdderive and identifier

Derive the MessageId trait for a Message.

MessageResponsederive

Derive the MessageResponse trait for a struct or enum.

RemoteAddressablederive and ipc

Derive the RemoteAddressable trait for an actor.

StableIdderive and identifier

Derive the StableId trait for a type.