Crate tonari_actor

Expand description

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 Message = usize;
    type Error = String;
    type Context = Context<Self::Message>;

    fn handle(&mut self, _context: &mut Self::Context, message: Self::Message) -> Result<(), String> {
        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 BareContext::subscribe() (also accessible on Context through Deref) 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.

§Async Actors

Support of async actors exists under the async feature flag. See the documentation of the async module for more info.

Re-exports§

pub use async::AsyncActor;

Modules§

async: Async Actors
timed: Tools to make a given actor able to receive delayed and recurring messages.

Structs§

Addr
BareContext: A Context without the Context::set_deadline() functionality. Used by timed and async actors. Context dereferences to this bare variant for system_handle and myself fields.
Capacity: Capacity of actor’s normal- and high-priority inboxes. 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 using a dereference to BareContext.
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.
SpawnBuilderWithAddress: After having configured the builder with an address it is possible to create and run the actor either on a new thread with Self::spawn() or on the current thread with Self::run_and_block().
SpawnBuilderWithoutAddress: A builder for configuring Actor spawning. You can specify your own Addr for the Actor, or let the system create a new address with either provided or default capacity.
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