Struct gstd::msg::CreateProgramFuture

pub struct CreateProgramFuture {
    pub waiting_reply_to: MessageId,
    pub program_id: ActorId,
    /* private fields */
}

Async functions that relate to creating programs wait for a reply from the program’s init function. These functions have the suffix _for_reply, such as crate::prog::create_program_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. Also, it keeps an identifier of a newly created program (ActorId).

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::CreateProgramFuture, prog, ActorId};
# use gstd::CodeId;

#[gstd::async_main]
async fn main() {
    # let code_id = CodeId::new([0; 32]);
    let future: CreateProgramFuture =
        prog::create_program_bytes_for_reply(code_id, b"salt", b"PING", 0, 0)
            .expect("Unable to create a program");
    let (prog_id, reply): (ActorId, Vec<u8>) = future.await.expect("Unable to get a reply");
}
# fn main() {}

Fields

waiting_reply_to: MessageId

A message identifier for an expected reply.

program_id: ActorId

An identifier of a newly created program.

Implementations

impl CreateProgramFuture

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 CreateProgramFuture

fn is_terminated(&self) -> bool

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

impl Future for CreateProgramFuture

type Output = Result<(ActorId, 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.