Module riot_wrappers::msg::v2

Available on riot_module_core_msg and crate feature with_msg_v2 only.

A safe-to-use interface for RIOT messages

This module’s main contribution is MessageSemantics, a chaining family of ZSTs that represent which types a thread expects to come in on which message numbers. From that, pairs of SendPorts (through which other threads send messages) and ReceivePorts (using which received messages are decoded) are split off.

For safety, the module relies on other components not tossing around messages indiscriminately. In Rust, senders are told through the SendPort how the recipient will transmute the data back. For C components, safe wrappers (TBD: will) require and consume appropriate tickets and from there on rely on the C side to only send what is described in the API.

Example

A comprehensive example of how this is currently used is maintained in the msg_tests example.

Stability

This module is still WIP and not subject to the semver-ish conduct upheld even in pre-1.0 versions of riot-wrappers. The module is hidden behind the with_msg_v2 feature to make that clear.

Status vs. Road map

Conceptually, this module is built for threads that can shut down again, or for receiving messages only in defined times (eg. when ). All information is preserved to allow ports split off from a thread’s message number pool to be recombined, pending messages to be drained and the thread set up to receive completely different messages on the same message type numbers.

Practically, this is not implemented, because threads are not commonly used in a run-and-shut-down pattern in RIOT. Some documentation refers to the process of recombination already.

It might still be tricky to actually perform that recombination safely, as there can be queued up messages. One pattern that is anticipated to work here is to define a single channel on which a SendPort can be returned through the message queue; thus, by the time it gets returned, the receiver can be sure that nothing else is left in the queue.

Re-exports

• pub use crate::msg::MsgSender as Sender;

Structs

• NoConfiguredMessages
• Processing
• ReceivePort
  Thread-bound information carrier that indicates that a given type number was reserved for this given content type.
• ReceivedMessage
  A message that was received while S was the current thread’s semantics.
• SendPort
  Object through which messages of a precise type can be sent to a precise thread.

Traits

• MessageSemantics
  Trait for types that indicate the current thread’s readiness to receive some set of messages