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
- 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 drops the crate::concurrency::JoinHandle for convenience and 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 drops the crate::concurrency::JoinHandle for convenience and assumes the actor implementation implements Default.
Type Aliases§
- Actor
Name - An actor’s name, equivalent to an Erlang
atom()
- Group
Name - A process group’s name, equivalent to an Erlang
atom()
- Scope
Name - A scope’s name, equivalent to an Erlang
atom()