Module msg 

Messaging API for Gear programs.

This module contains an API to process incoming messages and send outgoing ones. Messages are the primary communication interface between actors (users and programs).

Every Gear program has code that handles messages. During message processing, a program can send messages to other programs and users, including a reply to the initial message.

When some actor (user or program) sends a message to the program, it invokes this program by executing the handle function. The invoked program can obtain details of incoming messages by using this module’s API (source, size, load, id, value, etc.).

Optionally the program can send one or more messages to other actors. Also, it can send a reply that differs from a regular message in two ways:

• There can be no more than one reply;
• It is impossible to choose the reply’s destination, as it is always sent to the program invoker.

Note that messages and a reply are not sent immediately but collected during the program execution and enqueued after the execution successfully ends.

Structs

CodecCreateProgramFuture

Same as CreateProgramFuture, but allows decoding the reply’s payload instead of receiving a byte vector.

CodecMessageFuture

Same as MessageFuture, but allows decoding the reply’s payload instead of getting a byte vector.

CreateProgramFuture

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.

MessageFuture

Future returned by async functions related to message sending that wait for a reply (see sending functions with _for_reply suffix, e.g. send_bytes_for_reply).

MessageHandle

Message handle.

Functions

id

Get an identifier of the message that is currently being processed.

load

Get a payload of the message that is currently being processed.

load_bytes

Get a payload of the message that is currently being processed.

reply

Send a new message as a reply to the message being processed.

reply_bytes

Send a new message as a reply to the message that is currently being processed.

reply_bytes_from_reservation

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

reply_bytes_with_gas

Same as reply_bytes, but with an explicit gas limit.

reply_code

Get the reply code of the message being processed.

reply_commit

Finalize and send the current reply message.

reply_commit_from_reservation

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

reply_commit_with_gas

Same as reply_commit, but with an explicit gas limit.

reply_from_reservation

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

reply_input

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

reply_input_with_gas

Same as reply_input, but with an explicit gas limit.

reply_push

Push a payload part to the current reply message.

reply_push_input

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

reply_to

Get an identifier of the initial message on which the current handle_reply function is called.

reply_with_gas

Same as reply, but with an explicit gas limit.

send

Send a new message to the program or user.

send_bytes

Send a new message to the program or user.

send_bytes_delayed

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

send_bytes_delayed_from_reservation

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

send_bytes_for_reply

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

send_bytes_for_reply_as

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

send_bytes_from_reservation

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

send_bytes_from_reservation_for_reply

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

send_bytes_from_reservation_for_reply_as

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

send_bytes_with_gas

Same as send_bytes, but with an explicit gas limit.

send_bytes_with_gas_delayed

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

send_bytes_with_gas_for_reply

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

send_bytes_with_gas_for_reply_as

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

send_delayed

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

send_delayed_from_reservation

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

send_for_reply

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

send_for_reply_as

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

send_from_reservation

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

send_from_reservation_for_reply

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

send_from_reservation_for_reply_as

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

send_input

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

send_input_delayed

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

send_input_for_reply

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

send_input_for_reply_as

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

send_input_with_gas

Same as send_input, but with an explicit gas limit.

send_input_with_gas_delayed

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

send_input_with_gas_for_reply

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

send_input_with_gas_for_reply_as

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

send_with_gas

Same as send, but with an explicit gas limit.

send_with_gas_delayed

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

send_with_gas_for_reply

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

send_with_gas_for_reply_as

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

signal_code

Get the reply code of the message being processed.

signal_from

Get an identifier of the message which issued a signal.

size

Get the payload size of the message that is being processed.

source

Get the identifier of the message source (256-bit address).

value

Get the value associated with the message that is being processed.

with_read_on_stack_or_heap

Executes function f with provided message payload allocated on stack. If payload size is bigger than stack_buffer::MAX_BUFFER_SIZE, then allocation will be on heap.