Why: Message Queue#

template<typename T>
class MessageQueue#

A message queue for inter-thread communication with fixed-size messages.

The MessageQueue class provides a kernel object that allows threads to asynchronously send and receive fixed-size data items. Message queues are typically used to communicate structured data between threads in a producer-consumer pattern.

Key Features:

  • Fixed message boundaries: Each message is treated as a discrete unit

  • FIFO ordering: Messages are delivered in the order they were sent

  • Type-safe: Template parameter ensures compile-time type checking

  • Thread-safe: Multiple threads can safely send and receive concurrently

Template Parameters:

T – The type of messages to be sent through the queue. Must satisfy the memcpy_suitable concept (trivially copyable).

Public Functions

inline std::expected<T, OSError> get()#

Receive a message from the queue (blocking)

Blocks the calling thread until a message is available in the queue, then retrieves and returns it. Messages are received in FIFO order.

Warning

Not safe to call from an ISR! Use get_noblock() instead.

Returns:

The received message on success, or an OSError on failure

inline std::expected<T, OSError> get_noblock()#

Receive a message from the queue (non-blocking)

Attempts to retrieve a message from the queue without blocking. Returns immediately with an error if no message is available.

Note

ISR-safe: This method can be called from interrupt service routines.

Returns:

The received message on success, or an OSError (e.g., EAGAIN if empty)

inline std::expected<void, OSError> put(const T &elem)#

Send a message to the queue (blocking)

Blocks the calling thread if necessary until the message can be placed in the queue. The message is copied into the queue.

Warning

Not safe to call from an ISR! Use put_noblock() instead.

Parameters:

elem – The message to send

Returns:

Success (void) or an OSError on failure

inline std::expected<void, OSError> put_noblock(const T &elem)#

Send a message to the queue (non-blocking)

Attempts to place a message in the queue without blocking. Returns immediately with an error if the queue is full.

Note

ISR-safe: This method can be called from interrupt service routines.

Parameters:

elem – The message to send

Returns:

Success (void) or an OSError (e.g., EAGAIN if full)

inline int _pollfd() const#

Public Static Functions

static inline std::expected<MessageQueue<T>, OSError> create()#

Create a message queue.

Creates a new message queue for passing messages of type T between threads.

Returns:

A MessageQueue object on success, or an OSError on failure