Struct gstd::msg::MessageHandle

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

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

impl MessageHandle

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.

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.

pub fn push_input<Range: RangeBounds<usize>>(&self, range: Range) -> 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");
}

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.

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

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

• commit_for_reply
• https://docs.substrate.io/reference/scale-codec

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.

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");
}

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

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

• commit_with_gas_for_reply
• https://docs.substrate.io/reference/scale-codec

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.

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},
    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");
}

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

Same as commit_from_reservation, 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_from_reservation_for_reply_as

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

Same as commit_from_reservation, 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

• commit_from_reservation_for_reply
• https://docs.substrate.io/reference/scale-codec

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

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

Trait Implementations

impl AsRef<MessageHandle> for MessageHandle

fn as_ref(&self) -> &MessageHandle

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for MessageHandle

fn clone(&self) -> MessageHandle

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MessageHandle

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

Formats the value using the given formatter.

impl From<MessageHandle> for MessageHandle

fn from(other: MessageHandle) -> Self

Converts to this type from the input type.

impl From<MessageHandle> for MessageHandle

fn from(other: MessageHandle) -> Self

Converts to this type from the input type.

impl Output for MessageHandle

fn write(&mut self, bytes: &[u8])

Write to the output.

fn push_byte(&mut self, byte: u8)

Write a single byte to the output.

impl PartialEq for MessageHandle

fn eq(&self, other: &MessageHandle) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for MessageHandle

impl Eq for MessageHandle

impl StructuralEq for MessageHandle

impl StructuralPartialEq for MessageHandle