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.4"
Getting started
An example “ping-pong” actor might be the following
use ractor::{Actor, ActorRef, ActorProcessingErr};
/// [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"
#[async_trait::async_trait]
impl Actor for PingPong {
// An actor has a message type
type Msg = Message;
// and (optionally) internal state
type State = u8;
// 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>) -> 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>,
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 child actor, and as such is notified when the actor starts, stops, and fails (panics).
Supervision is presently left to the implementor, 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 failurs 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
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 prioritity 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::ActorRef;
pub use actor::actor_cell::ActorStatus;
pub use actor::actor_cell::ACTIVE_STATES;
pub use actor::errors::ActorErr;
pub use actor::errors::ActorProcessingErr;
pub use actor::errors::MessagingErr;
pub use actor::errors::SpawnErr;
pub use actor::messages::Signal;
pub use actor::messages::SupervisionEvent;
pub use actor::Actor;
pub use actor::ActorRuntime;
pub use actor_id::ActorId;
pub use message::Message;
pub use port::OutputMessage;
pub use port::OutputPort;
pub use port::RpcReplyPort;
Modules
Macros
call!
: Perform an infinite-time remote procedure call to an crate::Actorcall_t!
: Perform an finite-time remote procedure call to an crate::Actorcast!
takes an actor and a message and emits a crate::RactorErr error
which can be pattern matched on in order to derive the outputforward!
: Perform a remote procedure call to a crate::Actor
and forwards the result to another actor if successfulEnums
Traits
Type Definitions
atom()
atom()