µOS++ IIIe Reference  v6.3.15
“Perfekt ist nicht gut genug”
The third edition of µOS++, a POSIX inspired open source system, written in C++.
os::rtos::message_queue Class Reference

POSIX compliant message queue, using the default RTOS allocator. More...

#include <cmsis-plus/rtos/os.h>

Inherits os::rtos::internal::object_named_system.

Inherited by os::rtos::message_queue_allocated< Allocator >, and os::rtos::message_queue_inclusive< T, N >.

Classes

class  arena
 Storage for a static message queue. More...
 
class  attributes
 Message queue attributes. More...
 

Public Types

using allocator_type = memory::allocator< thread::stack::allocation_element_t >
 Default RTOS allocator. More...
 
using index_t = message_queue::size_t
 Type of list index storage. More...
 
using msg_size_t = uint16_t
 Type of message size storage. More...
 
using priority_t = uint8_t
 Type of message priority storage. More...
 
using size_t = uint8_t
 Type of a queue size storage. More...
 

Public Member Functions

template<typename T >
constexpr std::size_t compute_allocated_size_bytes (std::size_t msgs, std::size_t msg_size_bytes)
 Calculator for queue storage requirements. More...
 
Constructors & Destructor
 message_queue (std::size_t msgs, std::size_t msg_size_bytes, const attributes &attr=initializer, const allocator_type &allocator=allocator_type())
 Construct a message queue object instance. More...
 
 message_queue (const char *name, std::size_t msgs, std::size_t msg_size_bytes, const attributes &attr=initializer, const allocator_type &allocator=allocator_type())
 Construct a named message queue object instance. More...
 
virtual ~message_queue ()
 Destruct the message queue object instance. More...
 
Operators
bool operator== (const message_queue &rhs) const
 Compare memory queues. More...
 
Public Member Functions
result_t send (const void *msg, std::size_t nbytes, priority_t mprio=default_priority)
 Send a message to the queue. More...
 
result_t try_send (const void *msg, std::size_t nbytes, priority_t mprio=default_priority)
 Try to send a message to the queue. More...
 
result_t timed_send (const void *msg, std::size_t nbytes, clock::duration_t timeout, priority_t mprio=default_priority)
 Send a message to the queue with timeout. More...
 
result_t receive (void *msg, std::size_t nbytes, priority_t *mprio=nullptr)
 Receive a message from the queue. More...
 
result_t try_receive (void *msg, std::size_t nbytes, priority_t *mprio=nullptr)
 Try to receive a message from the queue. More...
 
result_t timed_receive (void *msg, std::size_t nbytes, clock::duration_t timeout, priority_t *mprio=nullptr)
 Receive a message from the queue with timeout. More...
 
std::size_t capacity (void) const
 Get queue capacity. More...
 
std::size_t length (void) const
 Get queue length. More...
 
std::size_t msg_size (void) const
 Get message size. More...
 
bool empty (void) const
 Check if the queue is empty. More...
 
bool full (void) const
 Check if the queue is full. More...
 
result_t reset (void)
 Reset the message queue. More...
 
Public Member Functions
const char * name (void) const
 Get object name. More...
 

Static Public Member Functions

Operators
static void * operator new (std::size_t bytes)
 Allocate space for a new object instance using the RTOS system allocator. More...
 
static void * operator new (std::size_t bytes, void *ptr)
 Emplace a new object instance. More...
 
static void * operator new[] (std::size_t bytes)
 Allocate space for an array of new object instances using the RTOS system allocator. More...
 
static void * operator new[] (std::size_t bytes, void *ptr)
 Emplace an array of new object instances. More...
 
static void operator delete (void *ptr, std::size_t bytes)
 Deallocate the dynamically allocated object instance. using the RTOS system allocator. More...
 
static void operator delete[] (void *ptr, std::size_t bytes)
 Deallocate the dynamically allocated array of object. instances using the RTOS system allocator. More...
 

Static Public Attributes

static constexpr priority_t default_priority = 0
 Default message priority. More...
 
static const attributes initializer
 Default message queue initialiser. More...
 
static constexpr msg_size_t max_msg_size = 0xFFFF
 Maximum message size. More...
 
static constexpr priority_t max_priority = 0xFF
 Maximum message priority. More...
 
static constexpr message_queue::size_t max_size = 0xFF
 Maximum queue size. More...
 
static constexpr index_t no_index = max_size
 Index value to represent an illegal index. More...
 

Detailed Description

POSIX compliant message queue, using the default RTOS allocator.

POSIX message queues allow threads to exchange data in the form of messages. Messages are transferred to and from a queue using send() and receive(). Each message has an associated priority, and messages are always delivered to the receiving process highest priority first.

The storage for the message queue is allocated dynamically, using the RTOS specific allocator (os::memory::allocator).

For special cases, the storage can be allocated outside the class and specified via the mq_queue_address and mq_queue_size_bytes attributes.

message_queue is a representative instance of the message_queue_allocated template; it is also used by the C API.

Example
// Define the message type.
typedef struct {
uint32_t id;
} msg_t;
// Define the queue size.
constexpr uint32_t queue_size = 5;
// The queue storage is allocated dynamically on the heap.
message_queue mq { queue_size, sizeof(msg_t) };
void
consumer(void)
{
// Do something
msg_t msg;
for (; some_condition();)
{
mq.receive(&msg, sizeof(msg));
// Process message
if (msg.id == 7)
{
// Something special
}
}
// Do something else.
}
void
producer(void)
{
// Do something
msg_t msg;
msg.id = 7;
mq.send(&msg, sizeof(msg));
// Do something else.
}
POSIX compatibility
Inspired by mqd_t from <mqueue.h> (IEEE Std 1003.1, 2013 Edition).

Definition at line 58 of file os-mqueue.h.

Constructor & Destructor Documentation

◆ message_queue() [1/2]

os::rtos::message_queue::message_queue ( std::size_t  msgs,
std::size_t  msg_size_bytes,
const attributes attr = initializer,
const allocator_type allocator = allocator_type () 
)

Construct a message queue object instance.

Parameters
[in]msgsThe number of messages.
[in]msg_size_bytesThe message size, in bytes.
[in]attrReference to attributes.
[in]allocatorReference to allocator. Default a local temporary instance.

This constructor shall initialise a message queue object with attributes referenced by attr. If the attributes specified by attr are modified later, the memory pool attributes shall not be affected. Upon successful initialisation, the state of the message queue object shall become initialised.

Only the message queue itself may be used for performing synchronisation. It is not allowed to make copies of message queue objects.

In cases where default message queue attributes are appropriate, the variable message_queue::initializer can be used to initialise message queue. The effect shall be equivalent to creating a message queue object with the simple constructor.

If the attributes define a storage area (via mq_queue_address and mq_queue_size_bytes), that storage is used, otherwise the storage is dynamically allocated using the RTOS specific allocator (rtos::memory::allocator).

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 382 of file os-mqueue.cpp.

◆ message_queue() [2/2]

os::rtos::message_queue::message_queue ( const char *  name,
std::size_t  msgs,
std::size_t  msg_size_bytes,
const attributes attr = initializer,
const allocator_type allocator = allocator_type () 
)

Construct a named message queue object instance.

Parameters
[in]namePointer to name.
[in]msgsThe number of messages.
[in]msg_size_bytesThe message size, in bytes.
[in]attrReference to attributes.
[in]allocatorReference to allocator. Default a local temporary instance.

This constructor shall initialise a named message queue object with attributes referenced by attr. If the attributes specified by attr are modified later, the memory pool attributes shall not be affected. Upon successful initialisation, the state of the message queue object shall become initialised.

Only the message queue itself may be used for performing synchronisation. It is not allowed to make copies of message queue objects.

In cases where default message queue attributes are appropriate, the variable message_queue::initializer can be used to initialise message queue. The effect shall be equivalent to creating a message queue object with the simple constructor.

If the attributes define a storage area (via mq_queue_address and mq_queue_size_bytes), that storage is used, otherwise the storage is dynamically allocated using the RTOS specific allocator (rtos::memory::allocator).

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 417 of file os-mqueue.cpp.

◆ ~message_queue()

os::rtos::message_queue::~message_queue ( )
virtual

Destruct the message queue object instance.

This destructor shall destroy the message queue object; the object becomes, in effect, uninitialised. An implementation may cause the destructor to set the object to an invalid value.

It shall be safe to destroy an initialised message queue object upon which no threads are currently blocked. Attempting to destroy a message queue object upon which other threads are currently blocked results in undefined behaviour.

If the storage for the message queue was dynamically allocated, it is deallocated using the same allocator.

Definition at line 473 of file os-mqueue.cpp.

Member Function Documentation

◆ capacity()

std::size_t os::rtos::message_queue::capacity ( void  ) const
inline

Get queue capacity.

Parameters
None.
Returns
The max number of messages that can be queued.
POSIX compatibility
Note
Can be invoked from Interrupt Service Routines. Extension to standard, no POSIX similar functionality identified.

Definition at line 1298 of file os-mqueue.h.

◆ compute_allocated_size_bytes()

template<typename T >
constexpr std::size_t os::rtos::message_queue::compute_allocated_size_bytes ( std::size_t  msgs,
std::size_t  msg_size_bytes 
)
inline

Calculator for queue storage requirements.

Parameters
msgsNumber of messages.
msg_size_bytesSize of message.
Returns
Total required storage in bytes, including internal alignment.

Definition at line 241 of file os-mqueue.h.

◆ empty()

bool os::rtos::message_queue::empty ( void  ) const
inline

Check if the queue is empty.

Parameters
None.
Return values
trueThe queue has no messages.
falseThe queue has some messages.
POSIX compatibility
Extension to standard, no POSIX similar functionality identified.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 1324 of file os-mqueue.h.

◆ full()

bool os::rtos::message_queue::full ( void  ) const
inline

Check if the queue is full.

Parameters
None.
Return values
trueThe queue is full.
falseThe queue is not full.
POSIX compatibility
Extension to standard, no POSIX similar functionality identified.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 1337 of file os-mqueue.h.

◆ length()

std::size_t os::rtos::message_queue::length ( void  ) const
inline

Get queue length.

Parameters
None.
Returns
The number of messages in the queue.
POSIX compatibility
Extension to standard, no POSIX similar functionality identified.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 1285 of file os-mqueue.h.

◆ msg_size()

std::size_t os::rtos::message_queue::msg_size ( void  ) const
inline

Get message size.

Parameters
None.
Returns
The message size, in bytes.
POSIX compatibility
Extension to standard, no POSIX similar functionality identified.
Note
Can be invoked from Interrupt Service Routines.

Definition at line 1311 of file os-mqueue.h.

◆ name()

const char * os::rtos::internal::object_named::name ( void  ) const
inlineinherited

Get object name.

Parameters
None.
Returns
A null terminated string.

All objects return a non-null string; anonymous objects return "-".

Note
Can be invoked from Interrupt Service Routines.

Definition at line 760 of file os-decls.h.

◆ operator delete()

void os::rtos::internal::object_named_system::operator delete ( void *  ptr,
std::size_t  bytes 
)
inlinestaticinherited

Deallocate the dynamically allocated object instance. using the RTOS system allocator.

Parameters
ptrPointer to object.
bytesNumber of bytes to deallocate.
Returns
Nothing.

The deallocation function (3.7.4.2) called by a delete-expression to render the value of ptr invalid.

ptr shall be a null pointer or its value shall be a value returned by an earlier call to the (possibly replaced) operator new() which has not been invalidated by an intervening call to operator delete(void*).

If ptr is null, does nothing. Otherwise, reclaims the storage allocated by the earlier call to operator new.

The storage is deallocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 134 of file os-inlines.h.

◆ operator delete[]()

void os::rtos::internal::object_named_system::operator delete[] ( void *  ptr,
std::size_t  bytes 
)
inlinestaticinherited

Deallocate the dynamically allocated array of object. instances using the RTOS system allocator.

Parameters
ptrPointer to array of objects.
bytesNumber of bytes to deallocate.
Returns
Nothing.

The deallocation function (3.7.4.2) called by the array form of a delete-expression to render the value of ptr invalid.

If ptr is null, does nothing. Otherwise, reclaims the storage allocated by the earlier call to operator new.

The storage is deallocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 155 of file os-inlines.h.

◆ operator new() [1/2]

void * os::rtos::internal::object_named_system::operator new ( std::size_t  bytes)
inlinestaticinherited

Allocate space for a new object instance using the RTOS system allocator.

Parameters
bytesNumber of bytes to allocate.
Returns
Pointer to allocated object.

The allocation function (3.7.4.1) called by a new-expression (5.3.4) to allocate a storage of size bytes suitably aligned to represent any object of that size. Return a non-null pointer to suitably aligned storage (3.7.4).

The storage is allocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 56 of file os-inlines.h.

◆ operator new() [2/2]

void * os::rtos::internal::object_named_system::operator new ( std::size_t  bytes,
void *  ptr 
)
inlinestaticinherited

Emplace a new object instance.

Parameters
bytesNumber of bytes to emplace.
ptrPointer to location to emplace the object.
Returns
Pointer to emplaced object.

The allocation function (3.7.4.1) called by a placement new-expression to allocate a storage of size bytes suitably aligned to represent any object of that size. Return a non-null pointer to suitably aligned storage (3.7.4).

The storage is allocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 93 of file os-inlines.h.

◆ operator new[]() [1/2]

void * os::rtos::internal::object_named_system::operator new[] ( std::size_t  bytes)
inlinestaticinherited

Allocate space for an array of new object instances using the RTOS system allocator.

Parameters
bytesNumber of bytes to allocate.
Returns
Pointer to allocated array.

The allocation function (3.7.4.1) called by the array form of a new-expression (5.3.4) to allocate a storage of size bytes suitably aligned to represent any array object of that size or smaller.

The storage is allocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 74 of file os-inlines.h.

◆ operator new[]() [2/2]

void * os::rtos::internal::object_named_system::operator new[] ( std::size_t  bytes,
void *  ptr 
)
inlinestaticinherited

Emplace an array of new object instances.

Parameters
bytesNumber of bytes to emplace.
ptrPointer to location to emplace the object.
Returns
Pointer to emplaced array.

The allocation function (3.7.4.1) called by the array form of a placement new-expression to allocate a storage of size bytes suitably aligned to represent any array object of that size or smaller.

The storage is allocated using the RTOS system allocator.

Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 110 of file os-inlines.h.

◆ operator==()

bool os::rtos::message_queue::operator== ( const message_queue rhs) const
inline

Compare memory queues.

Return values
trueThe given memory queue is the same as this memory queue.
falseThe memory queues are different.

Identical message queues should have the same memory address.

POSIX compatibility
Extension to standard, no POSIX similar functionality identified.

Definition at line 1272 of file os-mqueue.h.

◆ receive()

result_t os::rtos::message_queue::receive ( void *  msg,
std::size_t  nbytes,
priority_t mprio = nullptr 
)

Receive a message from the queue.

Parameters
[out]msgThe address where to store the dequeued message.
[in]nbytesThe size of the destination buffer. Must be lower than the value used when creating the queue.
[out]mprioThe address where to store the message priority. The default is nullptr.
Return values
result::okThe message was received.
EINVALA parameter is invalid or outside of a permitted range.
EMSGSIZEThe specified message length, nbytes, is greater than the message size attribute of the message queue.
EPERMCannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLEThe message could not be dequeued (extension to POSIX).
EBADMSGThe implementation has detected a data corruption problem with the message.
EINTRThe operation was interrupted.

The receive() function shall receive the oldest of the highest priority message(s) from the message queue. If the size of the buffer in bytes, specified by the nbytes argument, is less than the msg_size_bytes attribute of the message queue, the function shall fail and return an error. Otherwise, the selected message shall be removed from the queue and copied to the buffer pointed to by the msg argument.

If the value of nbytes is greater than message_queue::max_size, the result is implementation-defined.

If the argument mprio is not nullptr, the priority of the selected message shall be stored in the location referenced by mprio.

If the message queue is empty, receive() shall block until a message is enqueued on the message queue or until receive() is cancelled/interrupted. If more than one thread is waiting to receive a message when a message arrives at an empty queue and the Priority Scheduling option is supported, then the thread of highest priority that has been waiting the longest shall be selected to receive the message. Otherwise, it is unspecified which waiting thread receives the message.

POSIX compatibility
Inspired by mq_receive() with O_NONBLOCK not set, from <mqueue.h> (IEEE Std 1003.1, 2013 Edition).
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 1202 of file os-mqueue.cpp.

◆ reset()

result_t os::rtos::message_queue::reset ( void  )

Reset the message queue.

Parameters
None.
Return values
result::okThe queue was reset.
EPERMCannot be invoked from an Interrupt Service Routines.

Clear both send and receive counter and return the queue to the initial state.

POSIX compatibility
Extension to standard, no POSIX similar functionality identified.
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 1525 of file os-mqueue.cpp.

◆ send()

result_t os::rtos::message_queue::send ( const void *  msg,
std::size_t  nbytes,
priority_t  mprio = default_priority 
)

Send a message to the queue.

Parameters
[in]msgThe address of the message to enqueue.
[in]nbytesThe length of the message. Must be not higher than the value used when creating the queue.
[in]mprioThe message priority. The default is 0.
Return values
result::okThe message was enqueued.
EINVALA parameter is invalid or outside of a permitted range.
EMSGSIZEThe specified message length, nbytes, exceeds the message size attribute of the message queue.
EPERMCannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLEThe message could not be enqueue (extension to POSIX).
EINTRThe operation was interrupted.

The send() function shall add the message pointed to by the argument msg to the message queue. The nbytes argument specifies the length of the message, in bytes, pointed to by msg. The value of nbytes shall be less than or equal to the msg_size_bytes parameter of the message queue object, or send() shall fail.

If the specified message queue is not full, send() shall behave as if the message is inserted into the message queue at the position indicated by the mprio argument. A message with a larger numeric value of mprio shall be inserted before messages with lower values of mprio. A message shall be inserted after other messages in the queue, if any, with equal mprio. The value of mprio shall be less than message_queue::max_priority.

If the specified message queue is full, send() shall block until space becomes available to enqueue the message, or until send() is cancelled/interrupted. If more than one thread is waiting to send when space becomes available in the message queue and the Priority Scheduling option is supported, then the thread of the highest priority that has been waiting the longest shall be unblocked to send its message. Otherwise, it is unspecified which waiting thread is unblocked.

POSIX compatibility
Inspired by mq_send() with O_NONBLOCK not set, from <mqueue.h> (IEEE Std 1003.1, 2013 Edition).
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 870 of file os-mqueue.cpp.

◆ timed_receive()

result_t os::rtos::message_queue::timed_receive ( void *  msg,
std::size_t  nbytes,
clock::duration_t  timeout,
priority_t mprio = nullptr 
)

Receive a message from the queue with timeout.

Parameters
[out]msgThe address where to store the dequeued message.
[in]nbytesThe size of the destination buffer. Must be lower than the value used when creating the queue.
[in]timeoutThe timeout duration.
[out]mprioThe address where to store the message priority. The default is nullptr.
Return values
result::okThe message was received.
EINVALA parameter is invalid or outside of a permitted range.
EMSGSIZEThe specified message length, nbytes, is greater than the message size attribute of the message queue.
EPERMCannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLEThe message could not be dequeued (extension to POSIX).
EBADMSGThe implementation has detected a data corruption problem with the message.
EINTRThe operation was interrupted.
ETIMEDOUTNo message arrived on the queue before the specified timeout expired.

The timed_receive() function shall receive the oldest of the highest priority message(s) from the message queue. If the size of the buffer in bytes, specified by the nbytes argument, is less than the msg_size_bytes attribute of the message queue, the function shall fail and return an error. Otherwise, the selected message shall be removed from the queue and copied to the buffer pointed to by the msg argument.

If the value of nbytes is greater than message_queue::max_size, the result is implementation-defined.

If the argument mprio is not nullptr, the priority of the selected message shall be stored in the location referenced by mprio.

If the message queue is empty, timed_receive() shall block until a message is enqueued on the message queue or until timed_receive() is cancelled/interrupted. If more than one thread is waiting to receive a message when a message arrives at an empty queue and the Priority Scheduling option is supported, then the thread of highest priority that has been waiting the longest shall be selected to receive the message. Otherwise, it is unspecified which waiting thread receives the message.

The timed_receive() function shall receive the oldest of the highest priority messages from the message queue as described for the receive() function. However, if no message exists on the queue to satisfy the receive, the wait for such a message shall be terminated when the specified timeout expires.

The timeout shall expire after the number of time units (that is when the value of that clock equals or exceeds (now()+duration). The resolution of the timeout shall be the resolution of the clock on which it is based.

Under no circumstance shall the operation fail with a timeout if a message can be removed from the message queue immediately.

The clock used for timeouts can be specified via the clock attribute. By default, the clock derived from the scheduler timer is used, and the durations are expressed in ticks.

Compatible with POSIX mq_receive() with O_NONBLOCK set. http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_receive.html#

POSIX compatibility
Inspired by mq_timedreceive() with O_NONBLOCK not set, from <mqueue.h> (IEEE Std 1003.1, 2013 Edition).
Differences from the standard:
  • the timeout is not expressed as an absolute time point, but as a relative number of timer ticks (by default, the SysTick clock for CMSIS).
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 1412 of file os-mqueue.cpp.

◆ timed_send()

result_t os::rtos::message_queue::timed_send ( const void *  msg,
std::size_t  nbytes,
clock::duration_t  timeout,
priority_t  mprio = default_priority 
)

Send a message to the queue with timeout.

Parameters
[in]msgThe address of the message to enqueue.
[in]nbytesThe length of the message. Must be not higher than the value used when creating the queue.
[in]timeoutThe timeout duration.
[in]mprioThe message priority. The default is 0.
Return values
result::okThe message was enqueued.
EINVALA parameter is invalid or outside of a permitted range.
EMSGSIZEThe specified message length, nbytes, exceeds the message size attribute of the message queue.
EPERMCannot be invoked from an Interrupt Service Routines.
ETIMEDOUTThe timeout expired before the message could be added to the queue.
ENOTRECOVERABLEThe message could not be enqueue (extension to POSIX).
EINTRThe operation was interrupted.

The timed_send() function shall add the message pointed to by the argument msg to the message queue. The nbytes argument specifies the length of the message, in bytes, pointed to by msg. The value of nbytes shall be less than or equal to the msg_size_bytes attribute of the message queue object, or timed_send() shall fail.

If the message queue is not full, timed_send() shall behave as if the message is inserted into the message queue at the position indicated by the mprio argument. A message with a larger numeric value of mprio shall be inserted before messages with lower values of mprio. A message shall be inserted after other messages in the queue, if any, with equal mprio. The value of mprio shall be less than message_queue::max_priority.

If the message queue is full, the wait for sufficient room in the queue shall be terminated when the specified timeout expires.

The timeout shall expire after the number of time units (that is when the value of that clock equals or exceeds (now()+timeout). The resolution of the timeout shall be the resolution of the clock on which it is based.

Under no circumstance shall the operation fail with a timeout if there is sufficient room in the queue to add the message immediately.

The clock used for timeouts can be specified via the clock attribute. By default, the clock derived from the scheduler timer is used, and the durations are expressed in ticks.

POSIX compatibility
Inspired by mq_timedsend() with O_NONBLOCK not set, from <mqueue.h> (IEEE Std 1003.1, 2013 Edition).
Differences from the standard:
  • the timeout is not expressed as an absolute time point, but as a relative number of timer ticks (by default, the SysTick clock for CMSIS).
Warning
Cannot be invoked from Interrupt Service Routines.

Definition at line 1065 of file os-mqueue.cpp.

◆ try_receive()

result_t os::rtos::message_queue::try_receive ( void *  msg,
std::size_t  nbytes,
priority_t mprio = nullptr 
)

Try to receive a message from the queue.

Parameters
[out]msgThe address where to store the dequeued message.
[in]nbytesThe size of the destination buffer. Must be lower than the value used when creating the queue.
[out]mprioThe address where to store the message priority. The default is nullptr.
Return values
result::okThe message was received.
EINVALA parameter is invalid or outside of a permitted range.
EMSGSIZEThe specified message length, nbytes, is greater than the message size attribute of the message queue.
ENOTRECOVERABLEThe message could not be dequeued (extension to POSIX).
EBADMSGThe implementation has detected a data corruption problem with the message.
EWOULDBLOCKThe specified message queue is empty.

The try_receive() function shall try to receive the oldest of the highest priority message(s) from the message queue. If the size of the buffer in bytes, specified by the nbytes argument, is less than the msg_size_bytes attribute of the message queue, the function shall fail and return an error. Otherwise, the selected message shall be removed from the queue and copied to the buffer pointed to by the msg argument.

If the value of nbytes is greater than message_queue::max_size, the result is implementation-defined.

If the argument mprio is not nullptr, the priority of the selected message shall be stored in the location referenced by mprio.

If the message queue is empty, no message shall be removed from the queue, and try_receive() shall return an error.

POSIX compatibility
Inspired by mq_receive() with O_NONBLOCK set, from <mqueue.h> (IEEE Std 1003.1, 2013 Edition).
Differences from the standard:
  • for consistency reasons, EWOULDBLOCK is used, instead of EAGAIN
Note
Can be invoked from Interrupt Service Routines.

Definition at line 1314 of file os-mqueue.cpp.

◆ try_send()

result_t os::rtos::message_queue::try_send ( const void *  msg,
std::size_t  nbytes,
priority_t  mprio = default_priority 
)

Try to send a message to the queue.

Parameters
[in]msgThe address of the message to enqueue.
[in]nbytesThe length of the message. Must be not higher than the value used when creating the queue.
[in]mprioThe message priority. The default is 0.
Return values
result::okThe message was enqueued.
EWOULDBLOCKThe specified message queue is full.
EINVALA parameter is invalid or outside of a permitted range.
EMSGSIZEThe specified message length, nbytes, exceeds the message size attribute of the message queue.
ENOTRECOVERABLEThe message could not be enqueue (extension to POSIX).

The try_send() function shall try to add the message pointed to by the argument msg to the message queue. The nbytes argument specifies the length of the message, in bytes, pointed to by msg. The value of nbytes shall be less than or equal to the msg_size_bytes parameter of the message queue object, or try_send() shall fail.

If the message queue is not full, try_send() shall behave as if the message is inserted into the message queue at the position indicated by the mprio argument. A message with a larger numeric value of mprio shall be inserted before messages with lower values of mprio. A message shall be inserted after other messages in the queue, if any, with equal mprio. The value of mprio shall be less than message_queue::max_priority.

If the message queue is full, the message shall not be queued and try_send() shall return an error.

POSIX compatibility
Inspired by mq_send() with O_NONBLOCK set, from <mqueue.h> (IEEE Std 1003.1, 2013 Edition).
Differences from the standard:
  • for consistency reasons, EWOULDBLOCK is used, instead of EAGAIN
Note
Can be invoked from Interrupt Service Routines.

Definition at line 981 of file os-mqueue.cpp.


The documentation for this class was generated from the following files: