Module gcore::msg

Messaging API for Gear programs.

This module contains an API to process incoming messages and synchronously 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, read, 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.

Functions

• id
  Get an identifier of the message that is currently being processed.
• read
  Get a payload of the message that is currently being processed.
• read_at
  Get a payload of the message that is currently being processed, starting from some particular offset.
• reply
  Send a new message as a reply to the message that is currently being processed.
• 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 it from the gas limit provided with the incoming message.
• reply_input
  Same as reply, but relays the incoming message payload.
• reply_input_with_gas
  Same as reply_input, but with 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_commit
  Finalize and send the message formed in parts.
• send_commit_delayed
  Same as send_commit, but sends the message after the delay expressed in block count.
• send_commit_delayed_from_reservation
  Same as send_commit_from_reservation, but sends the message after the delay expressed in block count.
• send_commit_from_reservation
  Same as send_commit, but it spends gas from a reservation instead of borrowing it from the gas limit provided with the incoming message.
• send_commit_with_gas
  Same as send_commit, but with an explicit gas limit.
• send_commit_with_gas_delayed
  Same as send_commit_with_gas, but sends the message after the delay expressed in block count.
• 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 thedelay expressed in block count.
• 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_init
  Initialize a message to send formed in parts.
• send_input
  Same as send but uses the input buffer as a payload source.
• send_input_delayed
  Same as send_input, but sends delayed.
• send_input_with_gas
  Same as send_input, but with explicit gas limit.
• send_input_with_gas_delayed
  Same as send_input_with_gas, but sends delayed.
• send_push
  Push a payload part of the message to be sent in parts.
• send_push_input
  Same as send_push but uses the input buffer as a payload source.
• 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.
• 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
  Executes function f with provided message payload allocated on stack.