µOS++ IIIe Reference 7.0.0
The third edition of µOS++, a POSIX inspired open source framework, written in C++
Loading...
Searching...
No Matches
Message queues

C API message queue definitions. More...

Classes

struct  os_mqueue_attr_s
 Message queue attributes. More...
 
struct  os_mqueue_s
 Message queue object storage. More...
 

Typedefs

typedef struct os_mqueue_attr_s os_mqueue_attr_t
 Message queue attributes.
 
typedef uint8_t os_mqueue_prio_t
 Type of variables holding message queue priorities.
 
typedef struct os_mqueue_s os_mqueue_t
 Message queue object storage.
 

Message Queue Attributes Functions

void os_mqueue_attr_init (os_mqueue_attr_t *attr)
 Initialise the message queue attributes.
 

Message Queue Creation Functions

void os_mqueue_construct (os_mqueue_t *mqueue, const char *name, size_t msgs, size_t msg_size_bytes, const os_mqueue_attr_t *attr)
 Construct a statically allocated message queue object instance.
 
void os_mqueue_destruct (os_mqueue_t *mqueue)
 Destruct the statically allocated message queue object instance.
 
os_mqueue_tos_mqueue_new (const char *name, size_t msgs, size_t msg_size_bytes, const os_mqueue_attr_t *attr)
 Allocate a message queue object instance and construct it.
 
void os_mqueue_delete (os_mqueue_t *mqueue)
 Destruct the message queue object instance and deallocate it.
 

Message Queue Functions

const char * os_mqueue_get_name (os_mqueue_t *mqueue)
 Get the message queue name.
 
os_result_t os_mqueue_send (os_mqueue_t *mqueue, const void *msg, size_t nbytes, os_mqueue_prio_t mprio)
 Send a message to the queue.
 
os_result_t os_mqueue_try_send (os_mqueue_t *mqueue, const void *msg, size_t nbytes, os_mqueue_prio_t mprio)
 Try to send a message to the queue.
 
os_result_t os_mqueue_timed_send (os_mqueue_t *mqueue, const void *msg, size_t nbytes, os_clock_duration_t timeout, os_mqueue_prio_t mprio)
 Send a message to the queue with timeout.
 
os_result_t os_mqueue_receive (os_mqueue_t *mqueue, void *msg, size_t nbytes, os_mqueue_prio_t *mprio)
 Receive a message from the queue.
 
os_result_t os_mqueue_try_receive (os_mqueue_t *mqueue, void *msg, size_t nbytes, os_mqueue_prio_t *mprio)
 Try to receive a message from the queue.
 
os_result_t os_mqueue_timed_receive (os_mqueue_t *mqueue, void *msg, size_t nbytes, os_clock_duration_t timeout, os_mqueue_prio_t *mprio)
 Receive a message from the queue with timeout.
 
size_t os_mqueue_get_capacity (os_mqueue_t *mqueue)
 Get queue capacity.
 
size_t os_mqueue_get_length (os_mqueue_t *mqueue)
 Get queue length.
 
size_t os_mqueue_get_msg_size (os_mqueue_t *mqueue)
 Get message size.
 
bool os_mqueue_is_empty (os_mqueue_t *mqueue)
 Check if the queue is empty.
 
bool os_mqueue_is_full (os_mqueue_t *mqueue)
 Check if the queue is full.
 
os_result_t os_mqueue_reset (os_mqueue_t *mqueue)
 Reset the message queue.
 

Compatibility Macros

#define os_mqueue_create   os_mqueue_construct
 
#define os_mqueue_destroy   os_mqueue_destruct
 

Detailed Description

C API message queue definitions.

For the complete definition, see
RTOS C++ API
Examples
typedef struct my_msg_s
{
int i;
const char* s;
} my_msg_t;
int
os_main (int argc, char* argv[])
{
// Define two messages.
my_msg_t msg_out =
{ 1, "msg" };
my_msg_t msg_in =
{ 0, NULL };
{
// Simple queues, dynamically allocated.
os_mqueue_construct (&q1, "q1", 3, sizeof(my_msg_t), NULL);
os_mqueue_send (&q1, &msg_out, sizeof(msg_out), 0);
os_mqueue_try_send (&q1, &msg_out, sizeof(msg_out), 0);
os_mqueue_timed_send (&q1, &msg_out, 1, sizeof(msg_out), 0);
msg_in.i = 0;
os_mqueue_receive (&q1, &msg_in, sizeof(msg_in), NULL);
assert(msg_in.i = 1);
msg_in.i = 0;
os_mqueue_try_receive (&q1, &msg_in, sizeof(msg_in), NULL);
assert(msg_in.i = 1);
msg_in.i = 0;
os_mqueue_timed_receive (&q1, &msg_in, sizeof(msg_in), 1, NULL);
assert(msg_in.i = 1);
const char* str;
size_t n;
str = os_mqueue_get_name (&q1);
assert(strcmp (str, "q1") == 0);
assert(n == 3);
assert(n == 0);
assert(n == sizeof(my_msg_t));
}
{
// Static queue.
// TODO: add macro to compute size.
static char queue[1000];
aq2.mq_queue_addr = queue;
aq2.mq_queue_size_bytes = sizeof(queue);
os_mqueue_construct (&q2, "q2", 3, sizeof(my_msg_t), &aq2);
os_mqueue_send (&q2, &msg_out, sizeof(msg_out), 0);
msg_in.i = 0;
os_mqueue_receive (&q2, &msg_in, sizeof(msg_in), NULL);
assert(msg_in.i = 1);
}
}
os_clock_t * os_clock_get_rtclock(void)
Get rtclock (the real-time clock).
bool os_mqueue_is_full(os_mqueue_t *mqueue)
Check if the queue is full.
os_result_t os_mqueue_reset(os_mqueue_t *mqueue)
Reset the message queue.
os_result_t os_mqueue_timed_send(os_mqueue_t *mqueue, const void *msg, size_t nbytes, os_clock_duration_t timeout, os_mqueue_prio_t mprio)
Send a message to the queue with timeout.
os_result_t os_mqueue_receive(os_mqueue_t *mqueue, void *msg, size_t nbytes, os_mqueue_prio_t *mprio)
Receive a message from the queue.
os_result_t os_mqueue_try_receive(os_mqueue_t *mqueue, void *msg, size_t nbytes, os_mqueue_prio_t *mprio)
Try to receive a message from the queue.
size_t os_mqueue_get_msg_size(os_mqueue_t *mqueue)
Get message size.
bool os_mqueue_is_empty(os_mqueue_t *mqueue)
Check if the queue is empty.
const char * os_mqueue_get_name(os_mqueue_t *mqueue)
Get the message queue name.
os_result_t os_mqueue_send(os_mqueue_t *mqueue, const void *msg, size_t nbytes, os_mqueue_prio_t mprio)
Send a message to the queue.
void os_mqueue_destruct(os_mqueue_t *mqueue)
Destruct the statically allocated message queue object instance.
size_t os_mqueue_get_capacity(os_mqueue_t *mqueue)
Get queue capacity.
size_t os_mqueue_get_length(os_mqueue_t *mqueue)
Get queue length.
void os_mqueue_attr_init(os_mqueue_attr_t *attr)
Initialise the message queue attributes.
void os_mqueue_construct(os_mqueue_t *mqueue, const char *name, size_t msgs, size_t msg_size_bytes, const os_mqueue_attr_t *attr)
Construct a statically allocated message queue object instance.
os_result_t os_mqueue_try_send(os_mqueue_t *mqueue, const void *msg, size_t nbytes, os_mqueue_prio_t mprio)
Try to send a message to the queue.
os_result_t os_mqueue_timed_receive(os_mqueue_t *mqueue, void *msg, size_t nbytes, os_clock_duration_t timeout, os_mqueue_prio_t *mprio)
Receive a message from the queue with timeout.
int os_main(int argc, char *argv[])
Application entry point, running on the main thread context.
Message queue attributes.
void * mq_queue_addr
Pointer to user provided message queue area.
void * clock
Pointer to clock object instance.
size_t mq_queue_size_bytes
Size of user provided message queue area, in bytes.
Message queue object storage.

Macro Definition Documentation

◆ os_mqueue_create

#define os_mqueue_create   os_mqueue_construct

Definition at line 2428 of file os-c-api.h.

◆ os_mqueue_destroy

#define os_mqueue_destroy   os_mqueue_destruct

Definition at line 2429 of file os-c-api.h.

Typedef Documentation

◆ os_mqueue_attr_t

Message queue attributes.

Initialise this structure with os_mqueue_attr_init() and then set any of the individual members directly.

See also
os::rtos::message_queue::attributes

◆ os_mqueue_prio_t

typedef uint8_t os_mqueue_prio_t

Type of variables holding message queue priorities.

See also
os::rtos::message_queue::priority_t

Definition at line 1289 of file os-c-decls.h.

◆ os_mqueue_t

typedef struct os_mqueue_s os_mqueue_t

Message queue object storage.

This C structure has the same size as the C++ os::rtos::message_queue object and must be initialised with os_mqueue_create().

Later on a pointer to it can be used both in C and C++ to refer to the message queue object instance.

The members of this structure are hidden and should not be used directly, but only through specific functions.

See also
os::rtos::message_queue

Function Documentation

◆ os_mqueue_attr_init()

void os_mqueue_attr_init ( os_mqueue_attr_t attr)

Initialise the message queue attributes.

Parameters
[in]attrPointer to message queue attributes object instance.
Returns
Nothing.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue::attributes

Definition at line 2534 of file os-c-wrapper.cpp.

◆ os_mqueue_construct()

void os_mqueue_construct ( os_mqueue_t mqueue,
const char *  name,
size_t  msgs,
size_t  msg_size_bytes,
const os_mqueue_attr_t attr 
)

Construct a statically allocated message queue object instance.

Parameters
[in]mqueuePointer to message queue object instance storage.
[in]namePointer to name (may be NULL).
[in]msgsThe number of messages.
[in]msg_size_bytesThe message size, in bytes.
[in]attrPointer to attributes (may be NULL).
Returns
Nothing.
Note
Must be paired with os_mqueue_destruct().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue

Definition at line 2549 of file os-c-wrapper.cpp.

◆ os_mqueue_delete()

void os_mqueue_delete ( os_mqueue_t mqueue)

Destruct the message queue object instance and deallocate it.

Parameters
[in]mqueuePointer to dynamically allocated message queue object instance.
Returns
Nothing.

Destruct the message queue and deallocate the dynamically allocated space using the RTOS system allocator.

Note
Equivalent of C++ delete ptr_mqueue.
Must be paired with os_mqueue_new().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue

Definition at line 2615 of file os-c-wrapper.cpp.

◆ os_mqueue_destruct()

void os_mqueue_destruct ( os_mqueue_t mqueue)

Destruct the statically allocated message queue object instance.

Parameters
[in]mqueuePointer to message queue object instance.
Returns
Nothing.
Note
Must be paired with os_mqueue_construct().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue

Definition at line 2570 of file os-c-wrapper.cpp.

◆ os_mqueue_get_capacity()

size_t os_mqueue_get_capacity ( os_mqueue_t mqueue)

Get queue capacity.

Parameters
[in]mqueuePointer to message queue object instance.
Returns
The max number of messages that can be queued.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue::capacity()

Definition at line 2744 of file os-c-wrapper.cpp.

◆ os_mqueue_get_length()

size_t os_mqueue_get_length ( os_mqueue_t mqueue)

Get queue length.

Parameters
[in]mqueuePointer to message queue object instance.
Returns
The number of messages in the queue.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue::length()

Definition at line 2731 of file os-c-wrapper.cpp.

◆ os_mqueue_get_msg_size()

size_t os_mqueue_get_msg_size ( os_mqueue_t mqueue)

Get message size.

Parameters
[in]mqueuePointer to message queue object instance.
Returns
The message size, in bytes.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue::msg_size()

Definition at line 2757 of file os-c-wrapper.cpp.

◆ os_mqueue_get_name()

const char * os_mqueue_get_name ( os_mqueue_t mqueue)

Get the message queue name.

Parameters
[in]mqueuePointer to message queue object instance.
Returns
Null terminated string.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue::name()

Definition at line 2628 of file os-c-wrapper.cpp.

◆ os_mqueue_is_empty()

bool os_mqueue_is_empty ( os_mqueue_t mqueue)

Check if the queue is empty.

Parameters
[in]mqueuePointer to message queue object instance.
Return values
trueThe queue has no messages.
falseThe queue has some messages.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue::empty()

Definition at line 2770 of file os-c-wrapper.cpp.

◆ os_mqueue_is_full()

bool os_mqueue_is_full ( os_mqueue_t mqueue)

Check if the queue is full.

Parameters
[in]mqueuePointer to message queue object instance.
Return values
trueThe queue is full.
falseThe queue is not full.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue::full()

Definition at line 2783 of file os-c-wrapper.cpp.

◆ os_mqueue_new()

os_mqueue_t * os_mqueue_new ( const char *  name,
size_t  msgs,
size_t  msg_size_bytes,
const os_mqueue_attr_t attr 
)

Allocate a message queue object instance and construct it.

Parameters
[in]namePointer to name (may be NULL).
[in]msgsThe number of messages.
[in]msg_size_bytesThe message size, in bytes.
[in]attrPointer to attributes (may be NULL).
Returns
Pointer to new message queue object instance.

Dynamically allocate the message queue object instance using the RTOS system allocator and construct it.

Note
Equivalent of C++ new message_queue(...).
Must be paired with os_mqueue_delete().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue

Definition at line 2590 of file os-c-wrapper.cpp.

◆ os_mqueue_receive()

os_result_t os_mqueue_receive ( os_mqueue_t mqueue,
void *  msg,
size_t  nbytes,
os_mqueue_prio_t mprio 
)

Receive a message from the queue.

Parameters
[in]mqueuePointer to message queue object instance.
[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. Enter NULL if priorities are not used.
Return values
os_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.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue::receive()

Definition at line 2686 of file os-c-wrapper.cpp.

◆ os_mqueue_reset()

os_result_t os_mqueue_reset ( os_mqueue_t mqueue)

Reset the message queue.

Parameters
[in]mqueuePointer to message queue object instance.
Return values
os_okThe queue was reset.
EPERMCannot be invoked from an Interrupt Service Routines.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue::reset()

Definition at line 2796 of file os-c-wrapper.cpp.

◆ os_mqueue_send()

os_result_t os_mqueue_send ( os_mqueue_t mqueue,
const void *  msg,
size_t  nbytes,
os_mqueue_prio_t  mprio 
)

Send a message to the queue.

Parameters
[in]mqueuePointer to message queue object instance.
[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. Enter 0 if priorities are not used.
Return values
os_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.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue::send()

Definition at line 2641 of file os-c-wrapper.cpp.

◆ os_mqueue_timed_receive()

os_result_t os_mqueue_timed_receive ( os_mqueue_t mqueue,
void *  msg,
size_t  nbytes,
os_clock_duration_t  timeout,
os_mqueue_prio_t mprio 
)

Receive a message from the queue with timeout.

Parameters
[in]mqueuePointer to message queue object instance.
[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. Enter NULL if priorities are not used.
Return values
os_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.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue::timed_receive()

Definition at line 2716 of file os-c-wrapper.cpp.

◆ os_mqueue_timed_send()

os_result_t os_mqueue_timed_send ( os_mqueue_t mqueue,
const void *  msg,
size_t  nbytes,
os_clock_duration_t  timeout,
os_mqueue_prio_t  mprio 
)

Send a message to the queue with timeout.

Parameters
[in]mqueuePointer to message queue object instance.
[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. Enter 0 if priorities are not used.
Return values
os_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.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue::timed_send()

Definition at line 2671 of file os-c-wrapper.cpp.

◆ os_mqueue_try_receive()

os_result_t os_mqueue_try_receive ( os_mqueue_t mqueue,
void *  msg,
size_t  nbytes,
os_mqueue_prio_t mprio 
)

Try to receive a message from the queue.

Parameters
[in]mqueuePointer to message queue object instance.
[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. Enter NULL if priorities are not used.
Return values
os_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.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue::try_receive()

Definition at line 2701 of file os-c-wrapper.cpp.

◆ os_mqueue_try_send()

os_result_t os_mqueue_try_send ( os_mqueue_t mqueue,
const void *  msg,
size_t  nbytes,
os_mqueue_prio_t  mprio 
)

Try to send a message to the queue.

Parameters
[in]mqueuePointer to message queue object instance.
[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. Enter 0 if priorities are not used.
Return values
os_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).
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::message_queue::try_send()

Definition at line 2656 of file os-c-wrapper.cpp.