Crate joerl Copy item path

§joerl - An Erlang-inspired Actor Model Library for Rust

Named in tribute to Joe Armstrong, the creator of Erlang, joerl brings the power and elegance of the Erlang actor model to Rust using async/await.

§Features

• Actor Model: Lightweight actors that communicate via message passing
• Supervision Trees: Robust error handling with configurable restart strategies
• Links and Monitors: Actor relationships for failure detection and propagation
• Bounded Mailboxes: Backpressure support to prevent resource exhaustion
• Async/Await: Built on tokio for excellent performance
• Erlang Conventions: Familiar API for Erlang/OTP developers
• Distributed Clustering: EPMD-based node discovery and location transparency

§Quick Start

use joerl::{Actor, ActorContext, ActorSystem, Message};
use async_trait::async_trait;

// Define your actor
struct Counter {
    count: i32,
}

#[async_trait]
impl Actor for Counter {
    async fn started(&mut self, ctx: &mut ActorContext) {
        println!("Counter started with pid {}", ctx.pid());
    }

    async fn handle_message(&mut self, msg: Message, ctx: &mut ActorContext) {
        if let Some(cmd) = msg.downcast_ref::<&str>() {
            match *cmd {
                "increment" => self.count += 1,
                "get" => println!("Count: {}", self.count),
                _ => {}
            }
        }
    }
}

#[tokio::main]
async fn main() {
    let system = ActorSystem::new();
    let counter = system.spawn(Counter { count: 0 });
     
    counter.send(Box::new("increment")).await.unwrap();
    counter.send(Box::new("get")).await.unwrap();
}

§Erlang Terminology Mapping

§Architecture

The library is organized into several key modules:

• actor: Core actor trait and context
• system: Actor system runtime and registry
• message: Message types and signals
• mailbox: Bounded mailbox implementation
• supervisor: Supervision trees and restart strategies
• gen_server: Generic server behavior (Erlang’s gen_server)
• gen_statem: Generic state machine behavior (Erlang’s gen_statem)
• epmd: Node discovery and clustering (EPMD protocol)
• distributed: Distributed actor systems with location transparency
• error: Error types and results

§Panic Handling

joerl implements full Erlang/OTP-style panic handling. When an actor panics:

• The panic is caught and converted to ExitReason::Panic
• Linked actors receive EXIT signals
• Monitoring actors receive DOWN signals
• Supervisors automatically restart the panicked actor
• Cleanup always happens (no resource leaks)

See the panic_handling example for a comprehensive demonstration.