Struct ActorCell 

pub struct ActorCell { /* private fields */ }

An ActorCell is a reference to an Actor’s communication channels and provides external access to send messages, stop, kill, and generally interactor with the underlying Actor process.

The input ports contained in the cell will return an error should the underlying actor have terminated and no longer exist.

Implementations

impl ActorCell

pub fn get_id(&self) -> ActorId

Retrieve the super::Actor’s unique identifier ActorId

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

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>(&self) -> Option<bool>

where TMessage: Message,

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.

pub async fn spawn_linked<T>( &self, name: Option<String>, handler: T, startup_args: <T as Actor>::Arguments, ) -> Result<(ActorRef<<T as Actor>::Msg>, JoinHandle<()>), SpawnErr>

where T: Actor,

Spawn an actor of the given type as a child of this actor, automatically starting the actor. This ActorCell becomes the supervisor of the child actor.

• name: A name to give the actor. Useful for global referencing or debug printing
• handler The implementation of Self
• startup_args: Arguments passed to the pre_start call of the Actor to facilitate startup and initial state creation

Returns a [Ok((ActorRef, JoinHandle<()>))] upon successful start, denoting the actor reference along with the join handle which will complete when the actor terminates. Returns [Err(SpawnErr)] if the actor failed to start

impl ActorCell

pub async fn spawn_local_linked<T>( &self, name: Option<String>, startup_args: <T as ThreadLocalActor>::Arguments, spawner: ThreadLocalActorSpawner, ) -> Result<(ActorRef<<T as ThreadLocalActor>::Msg>, JoinHandle<()>), SpawnErr>

where T: ThreadLocalActor,

Spawn an actor of the given type as a thread-local child of this actor, automatically starting the actor. This ActorCell becomes the supervisor of the child actor.

• name: A name to give the actor. Useful for global referencing or debug printing
• handler The implementation of Self
• startup_args: Arguments passed to the pre_start call of the ThreadLocalActor to facilitate startup and initial state creation

Returns a [Ok((ActorRef, JoinHandle<()>))] upon successful start, denoting the actor reference along with the join handle which will complete when the actor terminates. Returns [Err(SpawnErr)] if the actor failed to start

Trait Implementations

impl Clone for ActorCell

fn clone(&self) -> ActorCell

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ActorCell

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

Formats the value using the given formatter.

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

fn from(value: ActorCell) -> ActorRef<TMessage>

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl Hash for ActorCell

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for ActorCell

fn eq(&self, other: &ActorCell) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for ActorCell