Struct Promise 

pub struct Promise<T> { /* private fields */ }

Result of a queued request or reply.

Requests return Promise<Message>; their wait selects the expected response type or takes the message directly. Replies return Promise<()>; their wait observes local writing and flushing, not peer receipt or processing.

Dropping a promise leaves the request or reply running with its original deadline. A timeout does not mean the peer stopped working. Completed results remain available after the session closes.

A buffered response counts toward the session’s inbound byte limit until Promise::wait or drop. It stays encoded until waiting decodes it. Late answers and answers with no matching request are discarded. Answers whose promises were dropped are also discarded. Their payloads are never decoded.

Each promise returns its result once:

use darkbio_wire::protocol::schema::DeviceInfoResponse;
use darkbio_wire::protocol::{Message, Promise};
fn take_twice(promise: Promise<Message>) {
    let _ = promise.wait::<DeviceInfoResponse>();
    let _ = promise.wait::<DeviceInfoResponse>();
}

Implementations

impl Promise<Message>

pub fn wait<T>(self) -> Result<T, Error>

where T: TryFrom<Message>, Error: From<T::Error>,

Blocks for completion, then decodes the response.

The response must be accepted before the request’s original deadline. Decoding is outside that deadline. An accepted response remains available after the deadline or closure.

Taking the response removes its bytes from the inbound byte count before decoding it. A peer’s error answer returns Error::Remote. Invalid protobuf returns Error::Malformed and closes its original session.

Selects the expected response type at this call, either through inference or wait::<Response>(). Message extraction checks the content variant and returns Error::UnexpectedResponse on mismatch. The Message enum can also be taken directly for application pattern matching.

impl Promise<()>

pub fn wait(self) -> Result<(), Error>

Blocks until the reply is written and flushed locally, under its original deadline.

The peer does not send another acknowledgment for this reply.

impl<T> Promise<T>

pub fn notify(&mut self, callback: impl FnOnce() + Send + 'static)

Runs callback once the result is ready.

Requests notify on a response or an error, replies on local write and flush completion or an error, so a notification implies neither success nor peer receipt. The result is published first, so Promise::wait then takes it without waiting for publication, though it still decodes a response.

Registering or receiving a notification neither decodes the response nor releases its retained bytes. They remain charged until waiting or drop. Deadlines are unchanged, and registration does not service expiry.

On a settled promise, the callback runs at once on the registering thread, even after its session is gone. Otherwise the thread settling the operation runs it, which can be a protocol worker. Either way it runs, and its captures drop, outside every wire lock, so it may call back into the session. It must return promptly and must not panic.

Dropping the promise drops a callback still waiting for settlement, without canceling the operation. A callback already taken by settlement still runs.

Panics

Panics if notification was already registered on this promise.

Trait Implementations

impl<T> Debug for Promise<T>

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

Shows the deadline, whether a notification is registered and whether the result has been published.

A notification lock held elsewhere leaves the completion out.

impl<T> Drop for Promise<T>

fn drop(&mut self)

Takes an unrun callback under the notification lock, then drops it outside.

The protocol never drops a handed-out promise under its session lock.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.