Trait riot_wrappers::msg::v2::MessageSemantics

source ·

pub trait MessageSemantics: Sized {
    // Required methods
    fn typeno_is_known(&self, typeno: u16) -> bool;
    unsafe fn drop(message: &mut ReceivedMessage<'_, Self>);

    // Provided methods
    fn split_off<NewType: Send, const NEW_TYPENO: u16>(
        self
    ) -> (Processing<Self, NewType, NEW_TYPENO>, ReceivePort<NewType, NEW_TYPENO>, SendPort<NewType, NEW_TYPENO>) { ... }
    fn receive(&self) -> ReceivedMessage<'_, Self> { ... }
    fn try_receive(&self) -> Option<ReceivedMessage<'_, Self>> { ... }
}

Available on riot_module_core_msg and crate feature with_msg_v2 only.

Expand description

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

In a sense, a MessageSemantics is factory for mutually nonconflicting ReceivePorts, and a tracker of what was alerady issued.

Required Methods§

source

fn typeno_is_known(&self, typeno: u16) -> bool

source

unsafe fn drop(message: &mut ReceivedMessage<'_, Self>)

Interpret a message according to these semantics, then drop it.

While not essential for safety this does ensure that droppable types are not forgotten when sent and not handled, at least if they arrive. (Can’t help if someone runs try_send and does no error handling).

If all drops are trivial, this (and the <ReceivedMessage as Drop>::drop() caller) should all fold into no code.
If code for a nontrivially dropped type comes after a decode(), the compiler should be able to see that b/c that value was ruled out for .type_ just before.

This is unsafe for the same reasons you can’t call Drop::drop(&mut T) (the compiler forbids it).

Provided Methods§

source

fn split_off<NewType: Send, const NEW_TYPENO: u16>( self ) -> (Processing<Self, NewType, NEW_TYPENO>, ReceivePort<NewType, NEW_TYPENO>, SendPort<NewType, NEW_TYPENO>)

Reduce the type into a new MessageSemantics that knows about one more typeno, and a ReceivePort that can be used to create a SendPort or to process incoming messages.

type NumberReceived = ReceivePort<u32, 1>;
type BoolReceived = ReceivePort<bool, 2>;
let (message_semantics, receive_num, send_num): (_, NumberReceived, _) = message_semantics.split_off();
let (message_semantics, receive_bool, send_bool): (_, BoolReceived, _) = message_semantics.split_off();

§Panics

… if the type number has already been used, or the type is too large to be sent in a message.

The conditions for these panics should be evaluatable at build time (i.e. not be part of optimized code); over time these will hopfully become static assertion errors.

source