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

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

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.
source§

impl Copy for MessageHandle

source§

impl Eq for MessageHandle

source§

impl StructuralEq 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
§

impl<T> Conv for T

§

fn conv<T>(self) -> T
where Self: Into<T>,

Converts self into T using Into<T>. 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
§

impl<T> FmtForward for T

§

fn fmt_binary(self) -> FmtBinary<Self>
where Self: Binary,

Causes self to use its Binary implementation when Debug-formatted.
§

fn fmt_display(self) -> FmtDisplay<Self>
where Self: Display,

Causes self to use its Display implementation when Debug-formatted.
§

fn fmt_lower_exp(self) -> FmtLowerExp<Self>
where Self: LowerExp,

Causes self to use its LowerExp implementation when Debug-formatted.
§

fn fmt_lower_hex(self) -> FmtLowerHex<Self>
where Self: LowerHex,

Causes self to use its LowerHex implementation when Debug-formatted.
§

fn fmt_octal(self) -> FmtOctal<Self>
where Self: Octal,

Causes self to use its Octal implementation when Debug-formatted.
§

fn fmt_pointer(self) -> FmtPointer<Self>
where Self: Pointer,

Causes self to use its Pointer implementation when Debug-formatted.
§

fn fmt_upper_exp(self) -> FmtUpperExp<Self>
where Self: UpperExp,

Causes self to use its UpperExp implementation when Debug-formatted.
§

fn fmt_upper_hex(self) -> FmtUpperHex<Self>
where Self: UpperHex,

Causes self to use its UpperHex implementation when Debug-formatted.
§

fn fmt_list(self) -> FmtList<Self>
where &'a Self: for<'a> IntoIterator,

Formats each item in a sequence. 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.

§

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

§

fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> R
where Self: Sized,

Pipes by value. This is generally the method you want to use. Read more
§

fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> R
where R: 'a,

Borrows self and passes that borrow into the pipe function. Read more
§

fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> R
where R: 'a,

Mutably borrows self and passes that borrow into the pipe function. Read more
§

fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
where Self: Borrow<B>, B: 'a + ?Sized, R: 'a,

Borrows self, then passes self.borrow() into the pipe function. Read more
§

fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R ) -> R
where Self: BorrowMut<B>, B: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.borrow_mut() into the pipe function. Read more
§

fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
where Self: AsRef<U>, U: 'a + ?Sized, R: 'a,

Borrows self, then passes self.as_ref() into the pipe function.
§

fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
where Self: AsMut<U>, U: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.as_mut() into the pipe function.
§

fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
where Self: Deref<Target = T>, T: 'a + ?Sized, R: 'a,

Borrows self, then passes self.deref() into the pipe function.
§

fn pipe_deref_mut<'a, T, R>( &'a mut self, func: impl FnOnce(&'a mut T) -> R ) -> R
where Self: DerefMut<Target = T> + Deref, T: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.deref_mut() into the pipe function.
source§

impl<T> Same for T

§

type Output = T

Should always be Self
§

impl<T> Tap for T

§

fn tap(self, func: impl FnOnce(&Self)) -> Self

Immutable access to a value. Read more
§

fn tap_mut(self, func: impl FnOnce(&mut Self)) -> Self

Mutable access to a value. Read more
§

fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Immutable access to the Borrow<B> of a value. Read more
§

fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Mutable access to the BorrowMut<B> of a value. Read more
§

fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Immutable access to the AsRef<R> view of a value. Read more
§

fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Mutable access to the AsMut<R> view of a value. Read more
§

fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Immutable access to the Deref::Target of a value. Read more
§

fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Mutable access to the Deref::Target of a value. Read more
§

fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self

Calls .tap() only in debug builds, and is erased in release builds.
§

fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self

Calls .tap_mut() only in debug builds, and is erased in release builds.
§

fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Calls .tap_borrow() only in debug builds, and is erased in release builds.
§

fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Calls .tap_borrow_mut() only in debug builds, and is erased in release builds.
§

fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Calls .tap_ref() only in debug builds, and is erased in release builds.
§

fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Calls .tap_ref_mut() only in debug builds, and is erased in release builds.
§

fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Calls .tap_deref() only in debug builds, and is erased in release builds.
§

fn tap_deref_mut_dbg<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Calls .tap_deref_mut() only in debug builds, and is erased in release builds.
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
§

impl<T> TryConv for T

§

fn try_conv<T>(self) -> Result<T, Self::Error>
where Self: TryInto<T>,

Attempts to convert self into T using TryInto<T>. 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<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> JsonSchemaMaybe for T