Struct ractor::actor::actor_ref::ActorRef

pub struct ActorRef<TMessage> { /* private fields */ }

An ActorRef is a strongly-typed wrapper over an ActorCell to provide some syntactic wrapping on the requirement to pass the actor’s message type everywhere.

An ActorRef is the primary means of communication typically used when interfacing with super::Actors

The ActorRef is SPECIFICALLY marked Sync, regardless of the message type because all usages of the message type are to send an owned instance of a message and in no case is that message instance shared across threads. This is guaranteed by the underlying Tokio channel usages. Without this manual marking of Sync on ActorRef, we would need to constrain the message type Message to be Sync which is overly restrictive.

Implementations

impl<TMessage> ActorRef<TMessage>

pub fn get_cell(&self) -> ActorCell

Retrieve a cloned ActorCell representing this ActorRef

pub fn notify_supervisor_and_monitors(&self, evt: SupervisionEvent)

Notify the supervisor and all monitors that a supervision event occurred. Monitors receive a reduced copy of the supervision event which won’t contain the crate::actor::BoxedState and collapses the crate::ActorProcessingErr exception to a String

• evt - The event to send to this crate::Actor’s supervisors

impl<TMessage> ActorRef<TMessage>

where TMessage: Message,

pub fn send_message( &self, message: TMessage ) -> Result<(), MessagingErr<TMessage>>

Send a strongly-typed message, constructing the boxed message on the fly

• message - The message to send

Returns [Ok(())] on successful message send, [Err(MessagingErr)] otherwise

pub fn where_is(name: ActorName) -> Option<ActorRef<TMessage>>

Try and retrieve a strongly-typed actor from the registry.

Alias of crate::registry::where_is

impl<TMessage> ActorRef<TMessage>

where TMessage: Message,

pub fn cast(&self, msg: TMessage) -> Result<(), MessagingErr<TMessage>>

Alias of cast

pub async fn call<TReply, TMsgBuilder>( &self, msg_builder: TMsgBuilder, timeout_option: Option<Duration> ) -> Result<CallResult<TReply>, MessagingErr<TMessage>>

where TMsgBuilder: FnOnce(RpcReplyPort<TReply>) -> TMessage,

Alias of call

pub fn call_and_forward<TReply, TForwardMessage, TMsgBuilder, TFwdMessageBuilder>( &self, msg_builder: TMsgBuilder, response_forward: &ActorRef<TForwardMessage>, forward_mapping: TFwdMessageBuilder, timeout_option: Option<Duration> ) -> Result<JoinHandle<CallResult<Result<(), MessagingErr<TForwardMessage>>>>, MessagingErr<TMessage>>

where TReply: Send + 'static, TMsgBuilder: FnOnce(RpcReplyPort<TReply>) -> TMessage, TForwardMessage: Message, TFwdMessageBuilder: FnOnce(TReply) -> TForwardMessage + Send + 'static,

Alias of call_and_forward

impl<TMessage> ActorRef<TMessage>

where TMessage: Message,

Add the timing functionality on top of the crate::ActorRef

pub fn send_interval<F>(&self, period: Duration, msg: F) -> JoinHandle<()>

where F: Fn() -> TMessage + Send + 'static,

Alias of send_interval

pub fn send_after<F>( &self, period: Duration, msg: F ) -> JoinHandle<Result<(), MessagingErr<TMessage>>>

where F: FnOnce() -> TMessage + Send + 'static,

Alias of send_after

pub fn exit_after(&self, period: Duration) -> JoinHandle<()>

Alias of exit_after

pub fn kill_after(&self, period: Duration) -> JoinHandle<()>

Alias of kill_after

Methods from Deref<Target = ActorCell>

pub fn get_id(&self) -> ActorId

Retrieve the super::Actor’s unique identifier ActorId

pub fn get_name(&self) -> Option<ActorName>

Retrieve the super::Actor’s name

pub fn get_status(&self) -> ActorStatus

Retrieve the current status of an super::Actor

Returns the super::Actor’s current ActorStatus

pub fn link(&self, supervisor: ActorCell)

Link this super::Actor to the provided supervisor

• supervisor - The supervisor super::Actor of this actor

pub fn unlink(&self, supervisor: ActorCell)

Unlink this super::Actor from the supervisor if it’s currently linked (if self’s supervisor is supervisor)

• supervisor - The supervisor to unlink this super::Actor from

pub fn monitor(&self, who: ActorCell)

Monitor the provided super::Actor for supervision events. An actor in ractor can only have a single supervisor, denoted by the link function, however they may have multiple monitors. Monitor’s receive copies of the SupervisionEvents, with non-cloneable information removed.

• who: The actor to monitor

pub fn unmonitor(&self, who: ActorCell)

Stop monitoring the provided super::Actor for supervision events.

• who: The actor to stop monitoring

pub fn clear_monitors(&self)

Clear all the self::Actors which are monitored by this self::Actor

pub fn kill(&self)

Kill this super::Actor forcefully (terminates async work)

pub async fn kill_and_wait( &self, timeout: Option<Duration> ) -> Result<(), RactorErr<()>>

Kill this super::Actor forcefully (terminates async work) and wait for the actor shutdown to complete

• timeout - An optional timeout duration to wait for shutdown to occur

Returns [Ok(())] upon the actor being stopped/shutdown. [Err(RactorErr::Messaging(_))] if the channel is closed or dropped (which may indicate some other process is trying to shutdown this actor) or [Err(RactorErr::Timeout)] if timeout was hit before the actor was successfully shut down (when set)

pub fn stop(&self, reason: Option<String>)

Stop this super::Actor gracefully (stopping message processing)

• reason - An optional string reason why the stop is occurring

pub async fn stop_and_wait( &self, reason: Option<String>, timeout: Option<Duration> ) -> Result<(), RactorErr<StopMessage>>

Stop the super::Actor gracefully (stopping messaging processing) and wait for the actor shutdown to complete

• reason - An optional string reason why the stop is occurring
• timeout - An optional timeout duration to wait for shutdown to occur

Returns [Ok(())] upon the actor being stopped/shutdown. [Err(RactorErr::Messaging(_))] if the channel is closed or dropped (which may indicate some other process is trying to shutdown this actor) or [Err(RactorErr::Timeout)] if timeout was hit before the actor was successfully shut down (when set)

pub fn send_message<TMessage>( &self, message: TMessage ) -> Result<(), MessagingErr<TMessage>>

where TMessage: Message,

Send a strongly-typed message, constructing the boxed message on the fly

Note: The type requirement of TActor assures that TMsg is the supported message type for TActor such that we can’t send boxed messages of an unsupported type to the specified actor.

• message - The message to send

Returns [Ok(())] on successful message send, [Err(MessagingErr)] otherwise

pub fn notify_supervisor_and_monitors(&self, evt: SupervisionEvent)

Notify the supervisor and all monitors that a supervision event occurred. Monitors receive a reduced copy of the supervision event which won’t contain the crate::actor::BoxedState and collapses the crate::ActorProcessingErr exception to a String

• evt - The event to send to this super::Actor’s supervisors

Trait Implementations

impl<TMessage> Clone for ActorRef<TMessage>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<TMessage> Debug for ActorRef<TMessage>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<TMessage> Deref for ActorRef<TMessage>

type Target = ActorCell

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<TMessage> From<ActorCell> for ActorRef<TMessage>

fn from(value: ActorCell) -> Self

Converts to this type from the input type.

impl<TActor> From<ActorRef<TActor>> for ActorCell

fn from(value: ActorRef<TActor>) -> Self

Converts to this type from the input type.

impl<I, O> OutputPortSubscriberTrait<I> for ActorRef<O>

where I: Message + Clone, O: Message + From<I>,

fn subscribe_to_port(&self, port: &OutputPort<I>)

Subscribe to the output port

impl<T> Sync for ActorRef<T>