Module gstd::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 signal 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
  Calls function f with read message payload on stack buffer.