restioson/xtra

🎭 A tiny actor framework

xtra

A tiny, fast, and safe actor framework. It is modelled around Actix (copyright and license here).

Features

• Safe: there is no unsafe code in xtra.
• Tiny: xtra is only around 2000 LoC.
• Lightweight: xtra has few dependencies, most of which are lightweight (except futures).
• Asynchronous Handler interface which allows async/await syntax with &mut self.
• Does not depend on its own runtime and can be run with any futures executor. Convenience spawn functions are provided for Tokio, async-std, smol, and wasm-bindgen-futures.
• Quite fast. Running on Tokio, <170ns time from sending a message to it being processed for sending without waiting for a result on my development machine with an AMD Ryzen 3 3200G.

Example

use xtra::prelude::*;

#[derive(Default, xtra::Actor)]
struct Printer {
    times: usize,
}

struct Print(String);

impl Handler<Print> for Printer {
    type Return = ();

    async fn handle(&mut self, print: Print, _ctx: &mut Context<Self>) {
        self.times += 1;
        println!("Printing {}. Printed {} times so far.", print.0, self.times);
    }
}

#[tokio::main]
async fn main() {
    let addr = xtra::spawn_tokio(Printer::default(), None);
    loop {
        addr.send(Print("hello".to_string()))
            .await
            .expect("Printer should not be dropped");
    }
}

For a longer example, check out Vertex, a chat application written with xtra and spaad on the server.

Okay, sounds great! How do I use it?

Check out the docs and the examples to get started! Enabling the tokio, async_std, smol, or wasm_bindgen features is recommended in order to enable some convenience methods (such as xtra::spawn_tokio). Which you enable will depend on which executor you want to use (check out their docs to learn more about each). If you have any questions, feel free to open an issue or message me on the Rust discord.

Keep in mind that xtra has a MSRV of 1.60.0.

Cargo features

• async_std: enables integration with async-std.
• smol: enables integration with smol. Note that this requires smol 1.1 as 1.1 had a minor breaking change from 1.0 which leads to xtra no longer compiling on 1.0 and 1.1 simultaneously.
• tokio: enables integration with tokio.
• wasm_bindgen: enables integration with wasm-bindgen, and particularly its futures crate.
• instrumentation: Adds a dependency on tracing and creates spans for message sending and handling on actors.
• sink: Adds Address::into_sink and MessageChannel::into_sink.
• macros: Enables the Actor custom derive macro.

Latest Breaking Changes

To see the breaking changes for each version, see here. The latest version is 0.6.0.