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:

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

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
source

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
source

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§

source§

impl AsRef<MessageHandle> for MessageHandle

source§

fn as_ref(&self) -> &MessageHandle

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

impl Clone for MessageHandle

source§

fn clone(&self) -> MessageHandle

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for MessageHandle

source§

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

Formats the value using the given formatter. Read more
source§

impl From<MessageHandle> for MessageHandle

source§

fn from(other: MessageHandle) -> Self

Converts to this type from the input type.
source§

impl From<MessageHandle> for MessageHandle

source§

fn from(other: MessageHandle) -> Self

Converts to this type from the input type.
source§

impl Output for MessageHandle

source§

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

Write to the output.
§

fn push_byte(&mut self, byte: u8)

Write a single byte to the output.
source§

impl PartialEq for MessageHandle

source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Copy for MessageHandle

source§

impl Eq for MessageHandle

source§

impl StructuralPartialEq for MessageHandle

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> CloneToUninit for T
where T: Copy,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<T> JsonSchemaMaybe for T