Crate tonari_actor

This crate aims to provide a minimalist and high-performance actor framework for Rust with significantly less complexity than other frameworks like Actix.

In this framework, each Actor is its own OS-level thread. This makes debugging noticeably simpler, and is suitably performant when the number of actors is less than or equal to the number of CPU threads.

Example

use tonari_actor::{Actor, Context, System};

struct TestActor {}
impl Actor for TestActor {
    type Context = Context<Self::Message>;
    type Error = ();
    type Message = usize;

    fn name() -> &'static str {
        "TestActor"
    }

    fn handle(&mut self, _context: &mut Self::Context, message: Self::Message) -> Result<(), ()> {
        println!("message: {}", message);

        Ok(())
    }
}

let mut system = System::new("default");

// will spin up a new thread running this actor
let addr = system.spawn(TestActor {}).unwrap();

// send messages to actors to spin off work...
addr.send(1usize).unwrap();

// ask the actors to finish and join the threads.
system.shutdown().unwrap();

tonari-actor also provides some extensions on top of the basic actor functionality:

Timing Message Delivery

On top of Context::set_deadline() and Actor::deadline_passed() building blocks there is a higher level abstraction for delayed and recurring messages in the timed module.

Publisher/subscriber Event System

For cases where you want a global propagation of “events”, you can implement the Event trait for your event type and then use Context::subscribe() and SystemHandle::publish() methods.

Keep in mind that the event system has an additional requirement that the event type needs to be Clone and is not intended to be high-throughput. Run the pub_sub benchmark to get an idea.

Modules

timed

Tools to make a given actor able to receive delayed and recurring messages.

Structs

Addr

Capacity

Capacity of actor’s normal- and high-priority inboxes. For each inbox type, None signifies default capacity of given actor. Converts from usize.

Context

An execution context for a specific actor. Specifically, this is useful for managing the lifecycle of itself (through the myself field) and other actors via the SystemHandle provided. A time-based deadline for receiving a message can be set using Self::set_deadline() and friends.

DisconnectedError

The actor message channel is disconnected.

PublishError

Error publishing an event.

Recipient

Similar to Addr, but rather than pointing to a specific actor, it is typed for any actor that handles a given message-response type.

SendError

Failures that can occur when sending a message to an actor.

SpawnBuilder

A builder for specifying how to spawn an Actor. You can specify your own Addr for the Actor, the capacity of the Actor’s inbox, and you can specify whether to spawn the Actor into its own thread or block on the current calling thread.

System

Systems are responsible for keeping track of their spawned actors, and managing their lifecycles appropriately.

SystemCallbacks

SystemHandle

Contains the “metadata” of the system, including information about the registry of actors currently existing within the system.

Enums

ActorError

Control

The set of available control messages that all actors respond to.

Priority

Urgency of a given message. All high-priority messages are delivered before normal priority.

SendErrorReason

Reasons why sending a message to an actor can fail.

Traits

Actor

The base actor trait.

Event

A marker trait for types which participate in the publish-subscribe system of the actor framework.

SendResultExt