Crate acktor 

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

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, Signal, message::{Handler, Message}};

#[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 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();
}

Modules

address

Traits and type definitions for the address of actor model.

cron

Repetitive task execution in an actor.

debug_trace

Debug trace macro.

derivederive

Derive macros for defining messages and message responses.

envelope

Traits and type definitions for the envelope of a message.

errors

Re-exports some error types from tokio.

message

Message passing between actors.

observer

Observer pattern for actors.

report

Error reporting macro.

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.