Crate simpl_actor

simpl_actor - A Rust library for actor-based concurrency, built on Tokio.

Features

• Simple Actor Definition: Define actors with minimal code using Rust structs and macros.
• Automatic Message Handling: Leverages Rust’s type system and async capabilities.
• Asynchronous & Synchronous Messaging: Flexible interaction patterns for actors.
• Lifecycle Management: Hooks for actor initialization, restart, and shutdown.

Quick Start

use simpl_actor::{actor, Actor, Spawn};

#[derive(Actor, Default)]
pub struct CounterActor { count: i64 }

#[actor]
impl CounterActor {
    #[message]
    pub fn inc(&mut self, amount: i64) { ... }

    #[message]
    pub fn inc(&mut self, amount: i64) { ... }

    #[message(infallible)]
    pub fn count(&self) -> i64 { ... }
}

let counter = CounterActor::new();
let actor = counter.spawn();

actor.inc(2).await?;
actor.dec(1).await?;
let count = actor.count().await?;

Messaging Variants

When you define a message in simpl_actor, two variants of the message handling function are automatically for syncronous and asyncronous processing:

#[actor]
impl MyActor {
    #[message]
    fn msg(&self) -> Result<i32, Err> {}
}

// Generates
impl MyActorRef {
    /// Sends the messages, waits for processing, and returns a response.
    async fn msg(&self) -> Result<i32, SendError>;
    /// Sends the message after a delay.
    fn msg_after(&self, delay: Duration) -> JoinHandle<Result<Result<i32, Err>, SendError>>;
    /// Sends the message asynchronously, not waiting for a response.
    fn msg_async(&self) -> Result<(), SendError>;
    /// Sends the message asynchronously after a delay.
    fn msg_async_after(&self, delay: Duration) -> JoinHandle<Result<(), SendError>>;
}

The _after and _async variants are only generated if the method does not have any lifetimes.

In other words, all parameters must be owned or &'static for the async variant to be generated, otherwise the actor might reference deallocated memory causing UB.

Structs

• PanicErr
  A shared error that occurs when an actor panics or returns an error from a hook in the Actor trait.

Enums

• ActorStopReason
  Reason for an actor being stopped.
• SendError
  Error that can occur when sending a message to an actor.

Traits

• Actor
  Defines the core functionality for actors within an actor-based concurrency model.
• ActorRef
  Provides functionality to stop and wait for an actor to complete based on an actor ref.
• Spawn
  Provides functionality to spawn actors and obtain references to them.

Type Aliases

• BoxError
  A boxed dyn std Error used in actor hooks.

Attribute Macros

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

Derive Macros

• Actor
  Derive macro implementing the Actor trait with default behaviour.