xtra

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

For better ergonomics with xtra, try the spaad crate.

Features

• Safe: there is no unsafe code in xtra.
• Tiny: xtra is only ~1.1kloc.
• Lightweight: it only depends on futures and async_trait by default.
• Asynchronous and synchronous message handlers.
• Simple asynchronous message handling interface which allows async/await syntax even when borrowing self.
• Does not depend on its own runtime and can be used with any futures executor (Tokio, async-std, smol, and wasm-bindgen-futures have the Actor::spawn method and other convenience methods implemented out of the box).
• 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.
• However, it is also relatively new and less mature than other options.

Example

```rust use xtra::prelude::*; use asynctrait::asynctrait;

struct Printer { times: usize, }

impl Printer { fn new() -> Self { Printer { times: 0 } } }

impl Actor for Printer {}

struct Print(String);

impl Message for Print { type Result = (); }

// In the real world, the synchronous SyncHandler trait would be better-suited

[async_trait]

impl Handler for Printer { async fn handle(&mut self, print: Print, _ctx: &mut Context) { self.times += 1; // Look ma, no ActorFuture! println!("Printing {}. Printed {} times so far.", print.0, self.times); } }

[tokio::main]

async fn main() { let addr = Printer::new().spawn(); loop { // Likewise, in the real world the .do_send method should be used here as it is about 2x as fast 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 nightly (on the server).

Too verbose? Check out the spaad sister-crate!

Okay, sounds great! How do I use it?

Check out the docs and the examples to get started! Enabling one of the with-tokio-0_2, with-async_std-1, with-smol-0_1, or with-wasm_bindgen-0_2 features is recommended in order to enable some convenience methods (such as Actor::spawn). Which you enable will depend on which executor you want to use (check out their docs to learn more about each). You can't, however, enable more than one of these features at once. If you have any questions, feel free to open an issue or message me on the Rust discord.

Nightly API

There is also a different nightly API, which is incompatible with the stable api. For an example, check out examples/nightly.rs. To enable it, remove the default features from the dependency in the Cargo.toml. This API uses GATs and Type Alias Impl Trait to remove one boxing of a future, but according to my benchmarks, this impact has little effect. Your mileage may vary. GATs are unstable and can cause undefined behaviour in safe rust, and the combination of GAT + TAIT can break rustdoc. Therefore, the tradeoff is a (possibly negligible) performance boost for less support and instability. Generally, the only situation I would recommend this to be used in is for code written for xtra 0.2.

Latest Breaking Changes

From version 0.2.x to 0.3.0: - The default API of the Handler trait has now changed to an async_trait so that xtra can compile on stable. - How to upgrade, alternative 1: change the implementations by annotating the implementation with #[async_trait], removing Responder and making handle an async fn which directly returns the message's result. - How to upgrade, alternative 2: if you want to avoid the extra box, you can disable the default stable feature in your Cargo.toml to keep the old API.

See the full list of breaking changes by version here

To do

• Examples in documentation