Struct gstd::msg::MessageFuture

pub struct MessageFuture {
    pub waiting_reply_to: MessageId,
    /* private fields */
}

Future returned by async functions related to message sending that wait for a reply (see sending functions with _for_reply suffix, e.g. send_bytes_for_reply).

To get the reply payload (in bytes), one should use .await syntax. After calling a corresponding async function, the program interrupts its execution until a reply arrives.

This future keeps the sent message identifier (MessageId to wake the program after a reply arrives.

Examples

The following example explicitly annotates variable types for demonstration purposes only. Usually, annotating them is unnecessary because they can be inferred automatically.

use gstd::msg::{self, MessageFuture};
# use gstd::ActorId;

#[gstd::async_main]
async fn main() {
    # let dest = ActorId::zero();
    let future: MessageFuture =
        msg::send_bytes_for_reply(dest, b"PING", 0, 0).expect("Unable to send");
    let reply: Vec<u8> = future.await.expect("Unable to get a reply");
}
# fn main() {}

Fields

waiting_reply_to: MessageId

A message identifier for an expected reply.

This identifier is generated by the corresponding send function (e.g. send_bytes).

Implementations

impl MessageFuture

pub fn up_to(self, duration: Option<u32>) -> Result<Self>

Postpone handling for a maximum amount of blocks that could be paid, that doesn’t exceed a given duration.

pub fn exactly(self, duration: Option<u32>) -> Result<Self>

Postpone handling for a given specific amount of blocks.

pub fn handle_reply<F: FnOnce() + 'static>(self, f: F) -> Result<Self>

Execute a function when the reply is received.

This callback will be executed in reply context and consume reply gas, so adequate reply_deposit should be supplied in *_for_reply call that comes before this. Note that the hook will still be executed on reply even after original future resolves in timeout.

Examples

Send message to echo program and wait for reply.

use gstd::{ActorId, msg, debug};

#[gstd::async_main]
async fn main() {
    let dest = ActorId::from(1); // Replace with correct actor id

    msg::send_bytes_for_reply(dest, b"PING", 0, 1_000_000)
        .expect("Unable to send")
        .handle_reply(|| {
            debug!("reply code: {:?}", msg::reply_code());

            if msg::load_bytes().unwrap_or_default() == b"PONG" {
               debug!("successfully received pong");
            }
        })
        .expect("Error setting reply hook")
        .await
        .expect("Received error");
}

Panics

Panics if this is called second time.

Trait Implementations

impl FusedFuture for MessageFuture

fn is_terminated(&self) -> bool

Returns true if the underlying future should no longer be polled.

impl Future for MessageFuture

type Output = Result<Vec<u8>, Error>

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.