Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Restioson/xtra
🎠A tiny actor framework
https://github.com/Restioson/xtra
actor-model async async-await asynchronous rust safe tiny
Last synced: about 1 month ago
JSON representation
🎠A tiny actor framework
- Host: GitHub
- URL: https://github.com/Restioson/xtra
- Owner: Restioson
- License: mpl-2.0
- Created: 2020-01-18T07:37:11.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-07-05T23:20:08.000Z (2 months ago)
- Last Synced: 2024-07-06T03:14:24.980Z (2 months ago)
- Topics: actor-model, async, async-await, asynchronous, rust, safe, tiny
- Language: Rust
- Homepage:
- Size: 559 KB
- Stars: 310
- Watchers: 6
- Forks: 36
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ccamel - Restioson/xtra - 🎠A tiny actor framework (Rust)
README
[](https://github.com/Restioson/xtra/actions/workflows/ci.yml)
# xtra
A tiny, fast, and safe actor framework. It is modelled around Actix (copyright and license [here](https://github.com/Restioson/xtra/blob/master/LICENSE-ACTIX)).
## 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](https://tokio.rs/), [async-std](https://async.rs/), [smol](https://github.com/stjepang/smol), and
[wasm-bindgen-futures](https://rustwasm.github.io/wasm-bindgen/api/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
```rust
use xtra::prelude::*;
#[derive(Default, xtra::Actor)]
struct Printer {
times: usize,
}
struct Print(String);
impl Handler for Printer {
type Return = ();
async fn handle(&mut self, print: Print, _ctx: &mut Context) {
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](https://github.com/Restioson/vertex/tree/development), a chat application written with xtra and spaad on the server.
## Okay, sounds great! How do I use it?
Check out the [docs](https://docs.rs/xtra) and the [examples](https://github.com/Restioson/xtra/tree/master/xtra/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](https://github.com/Restioson/xtra/issues/new) or message me on the [Rust discord](https://bit.ly/rust-community).
Keep in mind that `xtra` has a MSRV of 1.60.0.
## Cargo features
- `async_std`: enables integration with [async-std](https://async.rs/).
- `smol`: enables integration with [smol](https://github.com/smol-rs/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](https://tokio.rs).
- `wasm_bindgen`: enables integration with [wasm-bindgen](https://github.com/rustwasm/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](https://github.com/Restioson/xtra/blob/master/BREAKING-CHANGES.md).
The latest version is 0.6.0.