Skip to main content

Crate acktor

Crate acktor 

Source
Expand description

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 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

FeatureDefaultDescription
deriveYesEnables #[derive(Message)] and #[derive(MessageResponse)] macros.
tokio-tracingNoNames spawned actor tasks for tokio-console. Requires building with RUSTFLAGS="--cfg tokio_unstable".
bottleneck-warningNoEmits tracing::debug! logs when an observer’s mailbox is full during notification, useful for spotting slow consumers.

Re-exports§

pub use actor::Actor;
pub use actor::ActorContext;
pub use actor::ActorId;
pub use actor::ActorState;
pub use actor::Stopping;
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;
pub use message::MessageId;identifier
pub use stable_type_id::HasStableTypeId;identifier
pub use stable_type_id::StableTypeId;identifier

Modules§

actor
Traits and type definitions for actors.
address
Traits and type definitions for actor address.
channel
Channel primitives used by this crate.
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.
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§

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.

Constants§

DEFAULT_MAILBOX_CAPACITY
The default mailbox capacity for actors.

Traits§

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

Type Aliases§

BoxError
Alias for a type-erased error type.

Derive Macros§

HasStableTypeIdderive and identifier
Derive the HasStableTypeId trait for a type.
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.