Crate kameo

Kameo 🧚🏻

Fault-tolerant Async Actors Built on Tokio

• Async: Built on tokio, actors run asyncronously in their own isolated spawned tasks.
• Supervision: Link actors, creating dependencies through child/parent/sibbling relationships.
• MPSC Unbounded Channels: Uses mpsc channels for messaging between actors.
• Concurrent Queries: Support concurrent processing of queries when mutable state isn’t necessary.
• Panic Safe: Catches panics internally, allowing actors to be restarted.

Installing

[dependencies]
kameo = "*"

Defining an Actor without Macros

use kameo::Actor;
use kameo::message::{Context, Message};

// Define the actor state
struct Counter {
  count: i64,
}

impl Actor for Counter {}

// Define messages
struct Inc(u32);

impl Message<Inc> for Counter {
    type Reply = i64;

    async fn handle(&mut self, msg: Counter, _ctx: Context<'_, Self, Self::Reply>) -> Self::Reply {
        self.count += msg.0 as i64;
        self.count
    }
}

Defining an Actor with Macros

use kameo::{Actor, messages};

// Define the actor state
#[derive(Actor)]
struct Counter {
    count: i64,
}

// Define messages
#[messages]
impl Counter {
    #[message]
    fn inc(&mut self, amount: u32) -> i64 {
        self.count += amount as i64;
        self.count
    }
}

See generated macro code

// Derive Actor
impl kameo::actor::Actor for Counter {
    fn name(&self) -> Cow<'_, str> {
        Cow::Borrowed("Counter")
    }
}

// Messages
struct Inc { amount: u32 }

impl kameo::Message<Inc> for Counter {
    type Reply = i64;

    async fn handle(&mut self, msg: Counter, _ctx: kameo::message::Context<'_, Self, Self::Reply>) -> Self::Reply {
        self.inc(msg.amount)
    }
}

Spawning an Actor & Messaging

let counter_ref = kameo::spawn(Counter { count: 0 });

let count = counter_ref.send(Inc(42)).await?;
println!("Count is {count}");

Re-exports

• pub use actor::spawn;
• pub use actor::Actor;
• pub use reply::Reply;

Modules

• actor
  Actor abstractions and utilities for building concurrent, asynchronous systems.
• error
  Defines error handling constructs for kameo.
• message
  Messaging infrastructure for actor communication in kameo.
• reply
  Constructs for handling replies and errors in kameo’s actor communication.

Attribute Macros

• messages
  Attribute macro placed on impl blocks of actors to define messages.

Derive Macros

• Actor
  Derive macro implementing the Actor trait with default behaviour.
• Reply
  Derive macro implementing the Reply trait as an infallible reply.