README.md

Messages. Convenient asynchronous communication

Status:

Project info:

Description

messages is a runtime-agnostic actor library.

It is heavily inspired by actix, a great actor framework.

This crate can be used with any runtime, whether it's popular or not. However, for the biggest one (tokio and async-std) there is an optional built-in support enabling more convenient interface (such as an automatic actor spawning).

Key features

• Full runtime independence. Can be used with any possible runtime that can spawn futures.
• Low dependencies amount.
• Low amount of boilerplate without derive macros.
• Good performance (close to raw channels).
• Relevant (but sufficient) functionality only.

Which library should I choose?

actix is a great, thoughtful, polished, and optimized library. If it is possible for you, you should consider it as the main option.

However, if any of statements below apply to your use case, messages may be better:

• You can't or don't want to stick to the Actix runtime.
• Your tasks may not have the similar runtime expense (actix-rt does not have work stealing and thus some threads may be underloaded in that case).
• You are seeking for the simpler interface and don't want to implement asynchronous code atop of the initially sync interface.

But what about xactor?

xactor is another good library inspired by Actix. It initially was built for async-std but then gained tokio support.

Nonetheless, this library is not runtime-agnostic. It supports async-std and tokio v1, but is not (yet) compatible with another runtimes.

That being said, messages initially serves different purpose: provide a way to implement actor workflow without having to think about supported runtimes.

Asyncness

This library is async-first, meaning that everything is made with respect to asynchronous architecture. While in some cases synchronous interfaces could've been more performant, it'd make the interface much more bloated. If synchronous actor interface is preferred, consider using actix, as it provides one.

Performance

TL;DR: This library provides performance that is better than in actix (for asynchronous message handling; based on the ring benchmark used by actix itself) and is tied with futures channels.

More details are presented in the BENCHES.md.

Note: messages treats async and multi-threaded context as its main environment, thus it may be less suitable (or, more precisely, less efficient) for the partially sync context. For instance, the sync version of the ring benchmark is by 80% faster than this library.

Examples

With runtime features

use messages::prelude::*;

struct Example; // Most of the types can be an actor.

// While `Actor` implementation can be customized, it is not required.
#[async_trait]
impl Actor for Example {}

// Message handler that calculates sum of two numbers.
#[async_trait]
impl Handler<(u8, u8)> for Example {
    type Result = u16;
    async fn handle(&mut self, (a, b): (u8, u8), context: &Context<Self>) -> u16 {
        (a as u16) + (b as u16)
    }
}

// Notification handler that just writes received number to stdout.
#[async_trait]
impl Notifiable<u8> for Example {
    async fn notify(&mut self, input: u8, context: &Context<Self>) {
        println!("Received number {}", input);
    }
}

#[tokio::main]
async fn main() {
   let mut addr = Example.spawn();
   let result = addr.send((22, 20)).await.unwrap();
   assert_eq!(result, 42);
   addr.notify(42).await.unwrap();
   addr.stop().await;
   addr.wait_for_stop().await;  
}

Without runtime features

use messages::prelude::*;

struct Ping;

#[async_trait]
impl Actor for Ping {}

#[async_trait]
impl Handler<u8> for Ping {
    type Result = u8;
    async fn handle(&mut self, input: u8, context: &Context<Self>) -> u8 {
        input
    }
}

#[tokio::main]
async fn main() {
   let context = Context::new();
   let mut addr = context.address();
   let actor = Ping;
   // Could've been any other runtime.
   let mut task_handle = tokio::spawn(context.run(actor));
   let result = addr.send(42).await.unwrap();
   assert_eq!(result, 42);
   addr.stop().await;
   addr.wait_for_stop().await;
   task_handle.await.unwrap();
}

More

More examples can be found in the examples directory.

They are numbered and written in a manner so that the next example is always somewhat superior to the previous one. You can consider it to be a temporary alternative for a book (which is coming later).

List of currently provided examples:

• Ping: Simple ping actor without much of functionality.
• Notify: More verbose example showing capabilities of the actor interface.
• Fibonacci: Example of a coroutine actor, i.e. one that can process messages in parallel.
• Ring: Ring benchmark, mostly copied from the corresponding actix example.
• Timed stream: Example showing both how to attach stream to an actor and send timed notifications to it.
• async-std: Version of the Notify example adapted for async-std runtime.
• smol: Example of using a runtime not supported out of the box. In that case, smol.
• WebSocket: Simple actor-based echo websocket server (and a client to play with it).

Contributing

All kinds of contributions are really appreciated!

License

messages library is licensed under the MIT License. See LICENSE for details.