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
andasync_trait
by default. - Asynchronous and synchronous message handlers.
- Simple asynchronous message handling interface which allows
async
/await
syntax even when borrowingself
. - Does not depend on its own runtime and can be run with any futures executor (Tokio,
async-std, smol, and
wasm-bindgen-futures have the
Actor::spawn
convenience method 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
use *;
use async_trait;
;
// In the real world, the synchronous SyncHandler trait would be better-suited
async
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 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). 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 switch to it, enable the nightly
feature 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
Actor
now requiresSend
to implement. Previously, the trait itself did not, but using it did requireSend
.- How to upgrade: you probably never had a non-
Send
actor in the first place.
- How to upgrade: you probably never had a non-
- The
{Weak}Address::attach_stream
method now requires that the actor implementsHandler<M>
whereM: Into<KeepRunning> + Send
. This is automatically implemented for()
, returningKeepRunning::Yes
. This allows the user more control over the future spawned byattach_stream
, but is breaking if the message returned did not implementInto<KeepRunning>
/- How to upgrade: implement
Into<KeepRunning>
for all message types used inattach_stream
. To mimic previous behaviour, returnKeepRunning::Yes
in the implementation.
- How to upgrade: implement
See the full list of breaking changes by version here