Struct OutboundEnvelope

pub struct OutboundEnvelope { /* private fields */ }

Represents a message prepared for sending, including sender and optional recipient addresses.

An OutboundEnvelope is typically created by an agent (using methods like AgentHandle::create_envelope) before sending a message. It holds the MessageAddress of the sender (return_address) and optionally the MessageAddress of the recipient (recipient_address).

The primary methods for dispatching the message are OutboundEnvelope::send (asynchronous) and OutboundEnvelope::reply (synchronous wrapper).

Equality and hashing are based solely on the return_address.

Implementations

impl OutboundEnvelope

pub fn new(return_address: MessageAddress) -> Self

Creates a new OutboundEnvelope with only a return address specified.

The recipient address is initially set to None. Use OutboundEnvelope::send or OutboundEnvelope::reply to send the message, typically back to the return_address if no recipient is set later (though send_message_inner logic defaults to return_address if recipient_address is None).

Arguments

• return_address: The MessageAddress of the agent creating this envelope (the sender).

Returns

A new OutboundEnvelope instance.

pub fn reply_to(&self) -> MessageAddress

Returns a clone of the sender’s MessageAddress.

pub fn recipient(&self) -> &Option<MessageAddress>

Returns a reference to the optional recipient’s MessageAddress.

pub fn reply( &self, message: impl ActonMessage + 'static, ) -> Result<(), MessageError>

Sends a message using this envelope, blocking the current thread until sent.

Warning: This method spawns a blocking Tokio task and creates a new Tokio runtime internally to execute the asynchronous send operation. This is generally discouraged within an existing asynchronous context as it can lead to performance issues or deadlocks. Prefer using the asynchronous OutboundEnvelope::send method whenever possible.

This method is primarily intended for scenarios where an asynchronous context is not readily available, but its use should be carefully considered.

Arguments

• message: The message payload to send. Must implement ActonMessage and be 'static.

Returns

• Ok(()): If the message was successfully scheduled to be sent (actual delivery depends on the recipient).
• Err(MessageError): Currently, this implementation always returns Ok(()), but the signature allows for future error handling. Potential errors (like closed channels) are logged internally.

pub async fn send(&self, message: impl ActonMessage + 'static)

Sends a message asynchronously using this envelope.

This method takes the message payload, wraps it in an Arc, and calls the internal send_message_inner to dispatch it to the recipient’s channel. The recipient is determined by recipient_address if Some, otherwise it defaults to return_address.

This is the preferred method for sending messages from within an asynchronous context.

Arguments

• message: The message payload to send. Must implement ActonMessage and be 'static.

Trait Implementations

impl Clone for OutboundEnvelope

fn clone(&self) -> OutboundEnvelope

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for OutboundEnvelope

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

Formats the value using the given formatter.

impl Default for OutboundEnvelope

fn default() -> OutboundEnvelope

Returns the “default value” for a type.

impl Hash for OutboundEnvelope

Implements hashing for OutboundEnvelope based on the return_address.

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

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 OutboundEnvelope

Implements equality comparison for OutboundEnvelope based on the return_address.

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

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

const 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 OutboundEnvelope

Derives Eq based on the PartialEq implementation.