Struct gstd::msg::MessageHandle

source ·

pub struct MessageHandle(/* private fields */);

Expand description

Message handle.

Gear allows users and program interaction via messages. Message creation consists of the following parts: message initialization, filling the message with payload (can be gradual), and message sending.

/// Here are the functions that constitute the parts of forming and sending messages:

MessageHandle::init initializes the message
MessageHandle::push adds a payload to a message
MessageHandle::commit sends a message

The send transaction will be posted only after the execution of the message processing has been finished.

To identify a message that is being built from parts of a program, you should use MessageHandle obtained via MessageHandle::init.

§Examples

use gstd::msg::{self, MessageHandle};

#[no_mangle]
extern "C" fn handle() {
    let msg_handle = MessageHandle::init().expect("Unable to init");
    msg_handle.push(b"Hello,").expect("Unable to push");
    msg_handle.push(b" world!").expect("Unable to push");
    msg_handle
        .commit(msg::source(), 0)
        .expect("Unable to commit");
}

Implementations§

source §

impl MessageHandle

source

pub fn init() -> Result<Self>

Initialize a message to send formed in parts.

Gear allows programs to work with messages that consist of several parts. This function initializes a message built in parts and returns the corresponding MessageHandle.

source

pub fn push<T: AsRef<[u8]>>(&self, payload: T) -> Result<()>

Push a payload part of the message to be sent in parts.

Gear allows programs to work with messages in parts. This function adds a payload part to the message.

source

pub fn push_input(&self, range: impl RangeBounds<usize>) -> Result<()>

Same as push but uses the input buffer as a payload source.

The argument of this method is the index range defining the input buffer’s piece to be pushed back to the output.

§Examples

Send half of the incoming payload back to the sender.

use gstd::msg::{self, MessageHandle};

#[no_mangle]
extern "C" fn handle() {
    let msg_handle = MessageHandle::init().expect("Unable to init");
    msg_handle
        .push_input(0..msg::size() / 2)
        .expect("Unable to push");
    msg_handle
        .commit(msg::source(), 0)
        .expect("Unable to commit");
}

source

pub fn commit(self, program: ActorId, value: u128) -> Result<MessageId>

Finalize and send the message formed in parts.

Gear allows programs to work with messages that consist of several parts. This function finalizes the message built in parts and sends it.

The first argument is the address of the target account. The second argument is the value to be transferred from the current program account to the message target account.

source

pub fn commit_for_reply( self, program: ActorId, value: u128, reply_deposit: u64, ) -> Result<MessageFuture>

Same as commit, but the program will interrupt until the reply is received.

Argument reply_deposit: u64 used to provide gas for future reply handling (skipped if zero).

§See also

commit_for_reply_as

source

pub fn commit_for_reply_as<D: Decode>( self, program: ActorId, value: u128, reply_deposit: u64, ) -> Result<CodecMessageFuture<D>>

Same as commit, but the program will interrupt until the reply is received.

Argument reply_deposit: u64 used to provide gas for future reply handling (skipped if zero).

The output should be decodable via SCALE codec.

§See also

source

pub fn commit_delayed( self, program: ActorId, value: u128, delay: u32, ) -> Result<MessageId>

Same as commit, but sends the message after the delay expressed in block count.

source

pub fn commit_with_gas( self, program: ActorId, gas_limit: u64, value: u128, ) -> Result<MessageId>

Same as commit, but with an explicit gas limit.

§Examples

use gstd::msg::{self, MessageHandle};

#[no_mangle]
extern "C" fn handle() {
    let msg_handle = MessageHandle::init().expect("Unable to init");
    msg_handle.push(b"Hello,").expect("Unable to push");
    msg_handle.push(b" world!").expect("Unable to push");
    msg_handle
        .commit_with_gas(msg::source(), 10_000_000, 42)
        .expect("Unable to commit");
}

source

pub fn commit_with_gas_for_reply( self, program: ActorId, gas_limit: u64, value: u128, reply_deposit: u64, ) -> Result<MessageFuture>

Same as commit_with_gas, but the program will interrupt until the reply is received.

Argument reply_deposit: u64 used to provide gas for future reply handling (skipped if zero).

§See also

commit_with_gas_for_reply_as

source

pub fn commit_with_gas_for_reply_as<D: Decode>( self, program: ActorId, gas_limit: u64, value: u128, reply_deposit: u64, ) -> Result<CodecMessageFuture<D>>

Same as commit_with_gas, but the program will interrupt until the reply is received.

Argument reply_deposit: u64 used to provide gas for future reply handling (skipped if zero).

The output should be decodable via SCALE codec.

§See also

source

pub fn commit_with_gas_delayed( self, program: ActorId, gas_limit: u64, value: u128, delay: u32, ) -> Result<MessageId>

Same as commit_with_gas, but sends the message after the delay expressed in block count.

source

pub fn commit_from_reservation( self, id: ReservationId, program: ActorId, value: u128, ) -> Result<MessageId>

Same as commit, but it spends gas from the reservation instead of borrowing from the gas limit provided with the incoming message.

§Examples

use gstd::{
    msg::{self, MessageHandle},
    prelude::*,
    ReservationId,
};

#[no_mangle]
extern "C" fn handle() {
    let reservation_id = ReservationId::reserve(5_000_000, 100).expect("Unable to reserve");
    let msg_handle = MessageHandle::init().expect("Unable to init");
    msg_handle.push(b"Hello,").expect("Unable to push");
    msg_handle.push(b" world!").expect("Unable to push");
    msg_handle
        .commit_from_reservation(reservation_id, msg::source(), 42)
        .expect("Unable to commit");
}