sprite-core 0.1.7

On Crates

⚡ What is Sprite?

Sprite is a Rust library for building fault-tolerant, concurrent actor systems with a clean, declarative API inspired by React.

Instead of writing complex supervision trees and manual error handling, you write actor components — pure setup closures that declare state, message handlers, and children. If an actor panics, Sprite automatically resurrects it in under 50 nanoseconds with its state intact.

🚀 Quick Start

use sprite_core::{Engine, Message};

fn main() {
    let engine = Engine::new();

    let counter = engine.spawn("counter", |ctx| {
        // Like React's useState — survives crashes
        let count = ctx.use_state("count", 0i64);

        ctx.on_message(move |msg| {
            if msg == "inc" {
                count.update(|c| c + 1);
                println!("count = {}", count.get());
            }
        });
    });

    counter.send(Message::text("inc"));
    counter.send(Message::text("inc"));
}

🧩 Core Concepts

🔥 Fault Tolerance

     [ Panic in Actor ]
           │
           ▼
   catch_unwind catches it     (~0.05ms)
           │
           ▼
   Arena reset                  (~1ns)
           │
           ▼
   State already intact         (0ns — lives in shared store)
           │
           ▼
   Setup closure re-runs        (~1ms)
           │
           ▼
   Actor Fully Restored         (< 50ns for recovery core)

State created via use_state lives in a shared store outside the actor thread, so it survives panics automatically. The actor's scratch allocations (via bumpalo) are reset, but your data is safe.

🛡️ Circuit Breaker

If an actor panics more than 10 times in 5 seconds, Sprite trips a circuit breaker and halts it — preventing infinite crash loops.

engine.spawn("fragile", |ctx| {
    ctx.on_message(|_| panic!("always"));
    // After 10 recoveries, this actor stops.
});

📦 Installation

[dependencies]
sprite-core = { git = "https://github.com/dragprog/sprite-engine" }

🏗️ Advanced Examples

Actor Pool (load balancing)

use sprite_core::{Engine, Message, Pool};

let engine = Engine::new();
let pool = Pool::new(&engine, "worker", 4, |ctx| {
    ctx.on_message(|task| {
        println!("Worker {} processing: {:?}", ctx.id(), task);
    });
});

for i in 0..100 {
    pool.send(Message::int(i));
}

Broadcast

engine.broadcast(Message::text("shutdown"));

Named Actors

engine.spawn("logger", |ctx| {
    ctx.on_message(|msg| println!("{:?}", msg));
});

engine.send_named("logger", Message::text("hello"));
assert_eq!(engine.lookup("logger"), Some(id));

Timer

use sprite_core::Timer;
use std::time::Duration;

Timer::send_after(handle.tx.clone(), Duration::from_secs(5), Message::text("timeout"));

Builder API

use sprite_core::{Engine, ActorBuilder};

let handle = ActorBuilder::new("worker", |ctx| {
    ctx.on_message(|msg| { /* ... */ });
})
.arena_size(1024 * 128)
.max_recoveries(5)
.recovery_window(Duration::from_secs(10))
.spawn(&engine);

🧪 Running Tests

git clone https://github.com/dragprog/sprite-engine.git
cd sprite-engine
cargo test --workspace
cargo bench --bench recovery_speed
cargo bench --bench mailbox_throughput
cargo run --example counter
cargo run --example pool
cargo run --example broadcast

📊 Benchmarks

🤝 Contributing

1. Fork the repo (git checkout -b feature/cool-thing).
2. Keep the API surface minimal and ergonomic.
3. Ensure tests pass (cargo test).
4. Submit a PR with a concise breakdown.

📄 License

Distributed under the Apache License 2.0. See LICENSE for details.