runact 1.1.0

A Rust-native actor runtime with BEAM-style processes
Documentation

Runact

A Rust-native actor runtime combining BEAM-style lightweight processes, messaging, scheduling, and supervision with Rust's ownership model.

Features

  • Actor trait — synchronous fn handle(&mut self, msg, ctx) with typed messages
  • Work-stealing scheduler — per-worker RunQueue, steal-half protocol, reduction-based cooperative yield
  • Request-reply — Runtime::request() with RequestHandle::recv()/try_recv()/recv_timeout()
  • Supervision — RestartStrategy::OneForOne with exponential backoff
  • Compute pool — offload CPU-intensive work to a thread pool with panic isolation and cancellation
  • Timers — one-shot and periodic with drift correction
  • Resources — type-safe capability-based resource management
  • Backpressure — bounded mailbox with MailboxFull error on overflow
  • Async tasks — native executor for standard Rust Futures with Runtime::spawn_task, TaskHandle (recv/try_recv/recv_timeout), panic isolation, and deterministic shutdown; cancellation, task timers, and task groups are planned (boundary)
  • Observability — structured logging via tracing

Quick Start

use runact::{Actor, ActorId, ActorContext, ActorError, Runtime};

struct Greeter;

impl Actor for Greeter {
    type Message = String;

    fn handle(&mut self, msg: String, _ctx: &mut ActorContext) -> Result<(), ActorError> {
        println!("Hello, {}!", msg);
        Ok(())
    }
}

let mut runtime = Runtime::new().unwrap();
let id = runtime.spawn(Greeter).unwrap();
runtime.send(id, "world".to_string()).unwrap();

Documentation

  • Architecture — Full architectural document with runtime model, invariants, and development order
  • Async Runtime — Architectural boundary: Runact schedules asynchronous work, I/O libraries define it (Future executor, task lifecycle, cancellation, timers, task groups)
  • Vision — Design priorities and long-term evolution
  • Getting Started — Walkthrough of core APIs
  • Supervision — Supervision trees and restart strategies
  • Compute — CPU-intensive work offloading
  • Timers — One-shot and periodic timers
  • Resources — Capability-based resource management
  • Actor Communication Principles — 24 principles for message flow and invariants
  • Scheduler — BEAM-style scheduler with work stealing
  • Runtime API — Top-level Runtime API reference
  • Actors — Actor trait, ActorId, ActorContext, ownership model
  • Security — Capability-based security model
  • Object Model — Core runtime types reference
  • Protocol — Message envelope and request/reply protocol
  • API Reference

MSRV

Rust 1.85 (edition 2024).

License

MIT OR Apache-2.0