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