Struct 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

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: Message> ActorRef<TMessage>

pub fn get_derived<TFrom>(&self) -> DerivedActorRef<TFrom>

where TMessage: From<TFrom>, TFrom: TryFrom<TMessage>,

Constructs the DerivedActorRef for a specific type from ActorRef. This allows an actor which handles either a subset of the full actor’s messages or a convertable type, allowing hiding of the original message type through implementation of From conversion.

Returns a DerivedActorRef where the message type is convertable to the ActorRef’s original message type via From. In order to facilitate MessagingErr::SendErr the original message type also needs to be reverse convertable via TryFrom to the TFrom type.

This method will panic if a send error occurs, and the returned message cannot be converted back to the TFrom type. This should never happen, unless conversions are created incorrectly.

impl<TKey, TMsg> ActorRef<FactoryMessage<TKey, RetriableMessage<TKey, TMsg>>>

where TKey: JobKey, TMsg: Message,

pub fn submit_retriable_job( &self, job: Job<TKey, TMsg>, strategy: MessageRetryStrategy, ) -> Result<(), MessagingErr<FactoryMessage<TKey, RetriableMessage<TKey, TMsg>>>>

When you’re talking to a factory, which accepts “retriable” jobs, this convenience function sets up the retriable state for you and converts your job to a retriable equivalent.

• job: The traditional Job which will be auto-converted into a Job of RetriableMessage for you however the accepted field, if set, will be dropped as RetriableMessages do not support accepted replies, except on the first iteration
• strategy: The MessageRetryStrategy to use for this retriable message

Returns the result from the underlying cast operation to the factory’s ActorRef.

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 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 async fn wait(&self, timeout: Option<Duration>) -> Result<(), Timeout>

Wait for the actor to exit, optionally within a timeout

• timeout: If supplied, the amount of time to wait before returning an error and cancelling the wait future.

IMPORTANT: If the timeout is hit, the actor is still running. You should wait again for its exit.

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 drain(&self) -> Result<(), MessagingErr<()>>

Drain the actor’s message queue and when finished processing, terminate the actor.

Any messages received after the drain marker but prior to shutdown will be rejected

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

Drain the actor’s message queue and when finished processing, terminate the actor, notifying on this handler that the actor has drained and exited (stopped).

• timeout: The optional amount of time to wait for the drain to complete.

Any messages received after the drain marker but prior to shutdown will be rejected

pub fn notify_supervisor(&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

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

Stop any children of this actor, not waiting for their exit, and threading the optional reason to all children

• reason: The stop reason to send to all the children

This swallows and communication errors because if you can’t send a message to the child, it’s dropped the message channel, and is dead/stopped already.

pub fn try_get_supervisor(&self) -> Option<ActorCell>

Tries to retrieve this actor’s supervisor.

Returns None if this actor has no supervisor at the given instance or [Some(ActorCell)] supervisor if one is configured.

pub async fn stop_children_and_wait( &self, reason: Option<String>, timeout: Option<Duration>, )

Stop any children of this actor, and wait for their collective exit, optionally threading the optional reason to all children

• reason: The stop reason to send to all the children
• timeout: An optional timeout which is the maximum time to wait for the actor stop operation to complete

This swallows and communication errors because if you can’t send a message to the child, it’s dropped the message channel, and is dead/stopped already.

pub fn drain_children(&self)

Drain any children of this actor, not waiting for their exit

This swallows and communication errors because if you can’t send a message to the child, it’s dropped the message channel, and is dead/stopped already.

pub async fn drain_children_and_wait(&self, timeout: Option<Duration>)

Drain any children of this actor, and wait for their collective exit

• timeout: An optional timeout which is the maximum time to wait for the actor stop operation to complete

pub fn get_children(&self) -> Vec<ActorCell>

Retrieve the supervised children of this actor (if any)

Returns a Vec of ActorCells which are the children that are presently linked to this actor.

pub fn get_type_id(&self) -> TypeId

Retrieve the TypeId of this ActorCell which can be helpful for quick type-checking.

HOWEVER: Note this is an unstable identifier, and changes between Rust releases and may not be stable over a network call.

pub fn is_message_type_of<TMessage: Message>(&self) -> Option<bool>

Runtime check the message type of this actor, which only works for local actors, as remote actors send serializable messages, and can’t have their message type runtime checked.

Returns None if the actor is a remote actor, and we cannot perform a runtime message type check. Otherwise [Some(true)] for the correct message type or [Some(false)] for an incorrect type will returned.

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