Struct gabriel2::ActorRef

pub struct ActorRef<Actor, Message, State, Response, Error> { /* private fields */ }

The ActorRef struct represents a reference to an actor in the Actorlib framework. It contains the following fields:

• tx: A Mutex wrapping an Option that contains a sender part of a message passing channel. This is used to send messages to the actor’s task.

• join_handle: A Mutex wrapping an Option that contains a handle to the actor’s task. This is used to control the execution of the actor’s task.

• state: An Option that contains the current state of the actor, wrapped in an Arc<Mutex> for thread safety.

• self_ref: A Mutex wrapping an Option that contains a reference to the actor itself. This is useful for actors that need to send messages to themselves.

• message_id: A Mutex wrapping an integer that represents the ID of the last message sent to the actor.

• promise: A Mutex wrapping a HashMap that maps message IDs to one-shot channel senders. This is used to send responses back to the sender of a message.

• name: A String that represents the name of the actor.

• actor: An Arc that contains the actor.

• running: A Mutex wrapping a boolean that indicates whether the actor is currently running or not.

Type parameters

• Actor: The type of the actor.
• Message: The type of the messages that the actor can process.
• State: The type of the state of the actor.
• Response: The type of the response that the actor produces after processing a message.
• Error: The type of the error that the actor can produce.

Trait Implementations

impl<Actor: Handler<Actor = Actor, State = State, Message = Message, Error = Error, Response = Response> + SSSD, Message: SSSD, State: SSSD, Response: SSSD, Error: SSSD + Error + From<Error>> ActorRefTrait for ActorRef<Actor, Message, State, Response, Error>

async fn new( name: impl AsRef<str>, actor: Self::Actor, state: Self::State, buffer: usize, ) -> Result<Arc<Self>, Self::Error>

Creates a new ActorRef instance.

This function takes the following parameters:

• name: A String that represents the name of the actor.
• actor: An instance of the actor.
• state: The initial state of the actor.
• buffer: The size of the message buffer.

The function returns a Result that contains an Arc to the ActorRef instance in case of success, or an Error in case of failure.

The function performs the following steps:

1. Wraps the initial state in an Arc<Mutex>.
2. Creates a new message passing channel with the specified buffer size.
3. Creates a new ActorRef instance and wraps it in an Arc.
4. Spawns a new asynchronous task that listens for incoming messages and processes them.
5. Calls the pre_start method of the actor.
6. Sets the running flag of the ActorRef to true.
7. Returns the Arc to the ActorRef instance.

Type parameters

• Actor: The type of the actor. This type must implement the Handler trait and be Sync, Send, and 'static.
• Message: The type of the messages that the actor can process. This type must be Debug, Send, and Sync.
• State: The type of the state of the actor. This type must be Debug, Send, and Sync.
• Response: The type of the response that the actor produces after processing a message. This type must be Debug, Send, and Sync.
• Error: The type of the error that the actor can produce. This type must implement the std::error::Error trait and be Debug, Send, Sync, and From<std::io::Error>.

async fn state(&self) -> Result<Arc<Mutex<Self::State>>, Error>

Retrieves the current state of the actor.

This method is part of the ActorRef struct and is used to retrieve the current state of the actor. The state is stored in the state field of the ActorRef struct, which is an Option containing the state wrapped in an Arc<Mutex>.

The method clones the state field and logs a trace message containing the name of the actor and the state. If the state field is None, the method returns an error. Otherwise, it returns the state.

Returns

• Result<Arc<Mutex<State>>, std::io::Error>: The current state of the actor wrapped in an Arc<Mutex>, or an error if the state field is None.

type Actor = Actor

type State = State

type Error = Error

impl<Actor: Handler<Actor = Actor, State = State, Message = Message, Error = Error, Response = Response> + SSSD, Message: SSSD, State: SSSD, Response: SSSD, Error: SSSD + Error + From<Error>> ActorTrait for ActorRef<Actor, Message, State, Response, Error>

async fn ask(&self, msg: Message) -> Result<Response, Error>

Sends a message to the actor and waits for a response.

This method is part of the ActorRef struct and is used to send a message to the actor and wait for a response. This is done by sending the message and a unique message ID through a channel to the actor’s task, which processes the message and sends the response back through a one-shot channel.

The method locks the tx field of the ActorRef struct, which is an Option containing a sender part of a message passing channel. If the tx field is None, the method returns an error. Otherwise, it creates a new one-shot channel for the response, increments the message ID, inserts the sender part of the one-shot channel into the promise field of the ActorRef struct (which is a HashMap mapping message IDs to one-shot channel senders), and sends the message and the message ID through the tx channel.

After sending the message, the method awaits the receiver part of the one-shot channel. If the receiver receives a response, the method returns the response. If the receiver is closed without sending a response, the method returns an error.

Parameters

• msg: The message to send to the actor.

Returns

• Result<Response, Error>: The response from the actor, or an error if the actor failed to process the message or if the tx field is None.

async fn send(&self, msg: Message) -> Result<(), Error>

Sends a message to the actor without waiting for a response.

This method is part of the ActorRef struct and is used to send a message to the actor without waiting for a response. This is done by sending the message and a zero message ID through a channel to the actor’s task, which processes the message.

The method locks the tx field of the ActorRef struct, which is an Option containing a sender part of a message passing channel. If the tx field is None, the method returns an error. Otherwise, it sends the message and a zero message ID through the tx channel.

After sending the message, the method returns Ok(()) if the message was sent successfully, or an error if the message could not be sent.

Parameters

• msg: The message to send to the actor.

Returns

• Result<(), std::io::Error>: Ok(()) if the message was sent successfully, or an error if the message could not be sent or if the tx field is None.

async fn stop(&self) -> Result<(), Error>

Stops the actor.

This method is part of the ActorRef struct and is used to stop the actor’s execution.

The method performs the following steps:

1. Checks if the actor is already stopped. If it is, the method returns Ok(()).
2. Calls the pre_stop method of the actor.
3. Sets the running flag of the ActorRef to false.
4. Clears the tx and self_ref fields of the ActorRef.
5. Aborts the actor’s task if it is running.
6. Clears the join_handle field of the ActorRef.
7. Logs a debug message indicating that the actor has stopped.

Returns

• Result<(), Error>: Ok(()) if the actor was stopped successfully, or an Error if the pre_stop method of the actor returned an error.

type Message = Message

type Response = Response

type Error = Error

impl<Actor: Debug, Message: Debug, State: Debug, Response: Debug, Error: Debug> Debug for ActorRef<Actor, Message, State, Response, Error>

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

Formats the value using the given formatter.

impl<Actor, Message, State, Response, Error> Drop for ActorRef<Actor, Message, State, Response, Error>

fn drop(&mut self)

Executes the destructor for this type.