Crate ractor

Expand description

ractor: A pure-Rust actor framework. Inspired from Erlang’s gen_server, with the speed + performance of Rust!

§Installation

Install ractor by adding the following to your Cargo.toml dependencies

[dependencies]
ractor = "0.15"

The minimum supported Rust version (MSRV) is 1.64. However if you disable the async-trait feature, then you need Rust >= 1.75 due to the native use of async fn in traits. See the Rust blog.

§Getting started

An example “ping-pong” actor might be the following

use ractor::{Actor, ActorProcessingErr, ActorRef};

/// [PingPong] is a basic actor that will print
/// ping..pong.. repeatedly until some exit
/// condition is met (a counter hits 10). Then
/// it will exit
pub struct PingPong;

/// This is the types of message [PingPong] supports
#[derive(Debug, Clone)]
pub enum Message {
    Ping,
    Pong,
}
#[cfg(feature = "cluster")]
impl ractor::Message for Message {}

impl Message {
    // retrieve the next message in the sequence
    fn next(&self) -> Self {
        match self {
            Self::Ping => Self::Pong,
            Self::Pong => Self::Ping,
        }
    }
    // print out this message
    fn print(&self) {
        match self {
            Self::Ping => print!("ping.."),
            Self::Pong => print!("pong.."),
        }
    }
}

// the implementation of our actor's "logic"
#[cfg_attr(feature = "async-trait", ractor::async_trait)]
impl Actor for PingPong {
    // An actor has a message type
    type Msg = Message;
    // and (optionally) internal state
    type State = u8;
    // Startup arguments for actor initialization
    type Arguments = ();

    // Initially we need to create our state, and potentially
    // start some internal processing (by posting a message for
    // example)
    async fn pre_start(
        &self,
        myself: ActorRef<Self::Msg>,
        _: (),
    ) -> Result<Self::State, ActorProcessingErr> {
        // startup the event processing
        myself.send_message(Message::Ping).unwrap();
        Ok(0u8)
    }

    // This is our main message handler
    async fn handle(
        &self,
        myself: ActorRef<Self::Msg>,
        message: Self::Msg,
        state: &mut Self::State,
    ) -> Result<(), ActorProcessingErr> {
        if *state < 10u8 {
            message.print();
            myself.send_message(message.next()).unwrap();
            *state += 1;
        } else {
            myself.stop(None);
            // don't send another message, rather stop the agent after 10 iterations
        }
        Ok(())
    }
}

async fn run() {
    let (_, actor_handle) = Actor::spawn(None, PingPong, ())
        .await
        .expect("Failed to start actor");
    actor_handle.await.expect("Actor failed to exit cleanly");
}

which will output

$ cargo run
ping..pong..ping..pong..ping..pong..ping..pong..ping..pong..
$

§Supervision

Actors in ractor also support supervision. This is done by “linking” actors together in a supervisor-child relationship. A supervisor is responsible for the life cycle of the child actor, and as such is notified when the actor starts, stops, and fails (panics). If you set panic = 'abort' in your Cargo.toml, panics will start cause program termination and not be caught in the supervision flow.

Supervision is presently left to the implementor to outline handling of supervision events, but you can see a suite of supervision tests in crate::actor::tests::supervisor for examples on the supported functionality.

NOTE: panic’s in pre_start of an actor will cause failures to spawn, rather than supervision notified failures as the actor hasn’t “linked” to its supervisor yet. However failures in post_start, handle, handle_supervisor_evt, post_stop will notify the supervisor should a failure occur. See crate::Actor documentation for more information

There is additionally a “monitor” API which gives non-direct-supervision logic style monitoring akin to Erlang’s process monitors. This functionality is opt-in via feature monitors on the ractor crate.

§Messaging actors

The means of communication between actors is that they pass messages to each other. A developer can define any message type which is Send + 'static and it will be supported by ractor. There are 4 concurrent message types, which are listened to in priority. They are

Signals: Signals are the highest-priority of all and will interrupt the actor wherever processing currently is (this includes terminating async work). There is only 1 signal today, which is Signal::Kill, and it immediately terminates all work. This includes message processing or supervision event processing.
Stop: There is also a pre-defined stop signal. You can give a “stop reason” if you want, but it’s optional. Stop is a graceful exit, meaning currently executing async work will complete, and on the next message processing iteration Stop will take priority over future supervision events or regular messages. It will not terminate currently executing work, regardless of the provided reason.
SupervisionEvent: Supervision events are messages from child actors to their supervisors in the event of their startup, death, and/or unhandled panic. Supervision events are how an actor’s supervisor(s) are notified of events of their children and can handle lifetime events for them.
Messages: Regular, user-defined, messages are the last channel of communication to actors. They are the lowest priority of the 4 message types and denote general actor work. The first 3 messages types (signals, stop, supervision) are generally quiet unless it’s a lifecycle event for the actor, but this channel is the “work” channel doing what your actor wants to do!

Re-exports§

pub use actor::actor_cell::ActorCell;
pub use actor::actor_cell::ActorStatus;
pub use actor::actor_cell::ACTIVE_STATES;
pub use actor::actor_id::ActorId;
pub use actor::actor_ref::ActorRef;
pub use actor::derived_actor::DerivedActorRef;
pub use actor::messages::Signal;
pub use actor::messages::SupervisionEvent;
pub use actor::Actor;
pub use actor::ActorRuntime;
pub use errors::ActorErr;
pub use errors::ActorProcessingErr;
pub use errors::MessagingErr;
pub use errors::RactorErr;
pub use errors::SpawnErr;
pub use message::Message;
pub use port::OutputMessage;
pub use port::OutputPort;
pub use port::RpcReplyPort;

Modules§

actor: This module contains the basic building blocks of an actor.
concurrency: Shared concurrency primitives utilized within the library for different frameworks (tokio, async-std, etc)
errors: Actor error types
factory: Factory actors
macros: Macro helpers for remote procedure calls
message: Message trait definition for inter-actor messaging. Additionally with the cluster feature, it controls serialization logic for over-the-wire inter-actor communications
pg: Process groups (PG) are named groups of actors with a friendly name which can be used for retrieval of the process groups. Then within the group, either a random actor (for dispatch) can be selected or the whole group (broadcast), or a subset (partial-broadcast) can have a message sent to them. Common operations are to (a) upcast the group members to a strong-type’d actor then dispatch a message with crate::call or crate::cast.
port: Port implementations for signaling and reception of messages in the Ractor environment
registry: Represents an actor registry.
rpc: Remote procedure calls (RPC) are helpful communication primitives to communicate with actors
thread_local: The thread-local module provides support for managing tasks which are not Send safe, and must remain pinned to the same thread for their lifetime.
time: Timers for sending messages to actors periodically

Macros§

call: call!: Perform an infinite-time remote procedure call to an crate::Actor
call_t: call_t!: Perform an finite-time remote procedure call to an crate::Actor
cast: cast! takes an actor and a message and emits a crate::RactorErr error which can be pattern matched on in order to derive the output.
forward: forward!: Perform a remote procedure call to a crate::Actor and forwards the result to another actor if successful

Traits§

State: Represents the state of an actor. Must be safe to send between threads (same bounds as a Message)

Functions§

spawn: Perform a background-spawn of an actor. This is a utility wrapper over Actor::spawn which assumes the actor implementation implements Default.
spawn_local: Perform a background-spawn of an thread-local actor. This is a utility wrapper over thread_local::ThreadLocalActor::spawn which assumes the actor implementation implements Default.
spawn_named: Perform a background-spawn of an actor with the provided name. This is a utility wrapper over Actor::spawn which assumes the actor implementation implements Default.

Type Aliases§

ActorName: An actor’s name, equivalent to an Erlang atom()
GroupName: A process group’s name, equivalent to an Erlang atom()
ScopeName: A scope’s name, equivalent to an Erlang atom()

Crate ractorCopy item path