pub struct PreparedMessage { /* private fields */ }Expand description
Message with send resources reserved but not yet submitted; dropping it directly cancels the operation.
Created by MessageBuilder::prepare or MessageBuilder::try_prepare. The reservation
consumes send capacity; call Self::commit promptly after recording local state, or drop it
directly when the application abandons the send. Cancellation, session termination, or the
overall deadline can invalidate the reservation.
Implementations§
Source§impl PreparedMessage
impl PreparedMessage
Sourcepub fn receipt(&self) -> &MessageReceipt
pub fn receipt(&self) -> &MessageReceipt
Borrows the reserved message’s receipt, which can query its ID, observe state, or request cancellation before submission.
§Use cases
Clone the receipt into a local tracking table or pass it to another observer before the message can be written. It refers to the same operation before and after submission; a receipt clone neither submits the message nor extends the reservation’s lifetime. If the reservation is dropped, retained receipts observe its cancellation or existing terminal state.
§Example
use open_net::{ws::Sender, Result};
async fn observe_before_commit(sender: &Sender) -> Result<()> {
let prepared = sender.message("report:ready").prepare().await?;
let observer = prepared.receipt().clone();
println!("Operation ID before commit: {}", observer.id());
let committed = prepared.commit()?;
println!("Operation ID after commit: {}", committed.id());
observer.written().await
}Sourcepub fn commit(self) -> Result<MessageReceipt>
pub fn commit(self) -> Result<MessageReceipt>
Consumes the reservation, submits the message to the send queue, and returns a receipt for the same operation.
This method completes synchronously: it does not wait for capacity or a network write and
does not require the calling thread to enter a Tokio runtime. The operation is still checked for validity at submission; cancellation, closure, or expiration of the overall
deadline can cause failure. Failure returns only crate::NetError; the reservation and message body are not returned.
§Use cases
Use after local tracking has been recorded and business conditions have been confirmed,
allowing the reserved message to enter send scheduling. Success means submission only;
wait for MessageReceipt::written to confirm the local write. Consuming self ensures
that one reservation can be submitted only once; this does not provide exactly-once processing by the server.
§Example
use open_net::{ws::{MessageReceipt, OperationId, Sender}, Result};
use std::collections::HashMap;
fn register_and_commit(
sender: &Sender,
pending: &mut HashMap<OperationId, MessageReceipt>, // This table serves the current session only.
) -> Result<MessageReceipt> {
let prepared = sender.message("refresh:inventory").try_prepare()?;
let id = prepared.receipt().id();
pending.insert(id, prepared.receipt().clone());
match prepared.commit() {
Ok(receipt) => Ok(receipt),
Err(error) => {
pending.remove(&id); // Submission failed; remove the local record registered earlier.
Err(error)
}
}
}