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_code
  Get the reply code of the message being processed.
• reply_commit
  Finalize and send the current reply message.
• reply_input
  Same as reply but uses the input buffer as a payload source.
• 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.
• 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_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_delayed
  Same as send, 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_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.
• 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.