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_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.

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_t q1;
      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);
 
      n = os_mqueue_get_capacity (&q1);
      assert(n == 3);
 
      n = os_mqueue_get_length (&q1);
      assert(n == 0);
 
      n = os_mqueue_get_msg_size (&q1);
      assert(n == sizeof(my_msg_t));
 
      os_mqueue_is_empty (&q1);
 
      os_mqueue_is_full (&q1);
 
      os_mqueue_reset (&q1);
 
      os_mqueue_destruct (&q1);
    }
 
    {
      // Static queue.
      // TODO: add macro to compute size.
      static char queue[1000];
 
      os_mqueue_attr_t aq2;
      os_mqueue_attr_init (&aq2);
      aq2.mq_queue_addr = queue;
      aq2.mq_queue_size_bytes = sizeof(queue);
      aq2.clock = os_clock_get_rtclock ();
 
      os_mqueue_t q2;
      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_mqueue_destruct (&q2);
    }
}

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

typedef struct os_mqueue_attr_s 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] attr Pointer 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]	mqueue	Pointer to message queue object instance storage.
[in]	name	Pointer to name (may be NULL).
[in]	msgs	The number of messages.
[in]	msg_size_bytes	The message size, in bytes.
[in]	attr	Pointer 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] mqueue Pointer 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] mqueue Pointer 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] mqueue Pointer 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] mqueue Pointer 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] mqueue Pointer 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] mqueue Pointer 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] mqueue Pointer to message queue object instance.

Return values

true	The queue has no messages.
false	The 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] mqueue Pointer to message queue object instance.

Return values

true	The queue is full.
false	The 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]	name	Pointer to name (may be NULL).
[in]	msgs	The number of messages.
[in]	msg_size_bytes	The message size, in bytes.
[in]	attr	Pointer 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]	mqueue	Pointer to message queue object instance.
[out]	msg	The address where to store the dequeued message.
[in]	nbytes	The size of the destination buffer. Must be lower than the value used when creating the queue.
[out]	mprio	The address where to store the message priority. Enter `NULL` if priorities are not used.

Return values

os_ok	The message was received.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, is greater than the message size attribute of the message queue.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLE	The message could not be dequeued (extension to POSIX).
EBADMSG	The implementation has detected a data corruption problem with the message.
EINTR	The 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] mqueue Pointer to message queue object instance.

Return values

os_ok	The queue was reset.
EPERM	Cannot 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]	mqueue	Pointer to message queue object instance.
[in]	msg	The address of the message to enqueue.
[in]	nbytes	The length of the message. Must be not higher than the value used when creating the queue.
[in]	mprio	The message priority. Enter 0 if priorities are not used.

Return values

os_ok	The message was enqueued.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, exceeds the message size attribute of the message queue.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLE	The message could not be enqueue (extension to POSIX).
EINTR	The 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]	mqueue	Pointer to message queue object instance.
[out]	msg	The address where to store the dequeued message.
[in]	nbytes	The size of the destination buffer. Must be lower than the value used when creating the queue.
[in]	timeout	The timeout duration.
[out]	mprio	The address where to store the message priority. Enter `NULL` if priorities are not used.

Return values

os_ok	The message was received.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, is greater than the message size attribute of the message queue.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLE	The message could not be dequeued (extension to POSIX).
EBADMSG	The implementation has detected a data corruption problem with the message.
EINTR	The operation was interrupted.
ETIMEDOUT	No 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]	mqueue	Pointer to message queue object instance.
[in]	msg	The address of the message to enqueue.
[in]	nbytes	The length of the message. Must be not higher than the value used when creating the queue.
[in]	timeout	The timeout duration.
[in]	mprio	The message priority. Enter 0 if priorities are not used.

Return values

os_ok	The message was enqueued.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, exceeds the message size attribute of the message queue.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ETIMEDOUT	The timeout expired before the message could be added to the queue.
ENOTRECOVERABLE	The message could not be enqueue (extension to POSIX).
EINTR	The 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]	mqueue	Pointer to message queue object instance.
[out]	msg	The address where to store the dequeued message.
[in]	nbytes	The size of the destination buffer. Must be lower than the value used when creating the queue.
[out]	mprio	The address where to store the message priority. Enter `NULL` if priorities are not used.

Return values

os_ok	The message was received.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, is greater than the message size attribute of the message queue.
ENOTRECOVERABLE	The message could not be dequeued (extension to POSIX).
EBADMSG	The implementation has detected a data corruption problem with the message.
EWOULDBLOCK	The 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]	mqueue	Pointer to message queue object instance.
[in]	msg	The address of the message to enqueue.
[in]	nbytes	The length of the message. Must be not higher than the value used when creating the queue.
[in]	mprio	The message priority. Enter 0 if priorities are not used.

Return values

os_ok	The message was enqueued.
EWOULDBLOCK	The specified message queue is full.
EINVAL	A parameter is invalid or outside of a permitted range.
EMSGSIZE	The specified message length, nbytes, exceeds the message size attribute of the message queue.
ENOTRECOVERABLE	The 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.

Classes

Typedefs

Message Queue Attributes Functions

Message Queue Creation Functions

Message Queue Functions

Compatibility Macros

Detailed Description

Macro Definition Documentation

◆ os_mqueue_create

◆ os_mqueue_destroy

Typedef Documentation

◆ os_mqueue_attr_t

◆ os_mqueue_prio_t

◆ os_mqueue_t

Function Documentation

◆ os_mqueue_attr_init()

◆ os_mqueue_construct()

◆ os_mqueue_delete()

◆ os_mqueue_destruct()

◆ os_mqueue_get_capacity()

◆ os_mqueue_get_length()

◆ os_mqueue_get_msg_size()

◆ os_mqueue_get_name()

◆ os_mqueue_is_empty()

◆ os_mqueue_is_full()

◆ os_mqueue_new()

◆ os_mqueue_receive()

◆ os_mqueue_reset()

◆ os_mqueue_send()

◆ os_mqueue_timed_receive()

◆ os_mqueue_timed_send()

◆ os_mqueue_try_receive()

◆ os_mqueue_try_send()