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

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 2432 of file os-c-api.h.

os_mqueue_destroy

#define os_mqueue_destroy   os_mqueue_destruct

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

Typedef Documentation

os_mqueue_attr_t

typedef struct os_mqueue_attr_s os_mqueue_attr_t

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

See also

os::rtos::message_queue::priority_t

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

os_mqueue_t

typedef struct os_mqueue_s os_mqueue_t

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

)

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 2721 of file os-c-wrapper.cpp.

{
  assert (attr != nullptr);
  new (attr) message_queue::attributes ();
}

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
	)

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 2736 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  if (attr == nullptr)
    {
      attr = (const os_mqueue_attr_t*)&message_queue::initializer;
    }
  new (mqueue) message_queue (name, msgs, msg_size_bytes,
                              (const message_queue::attributes&)*attr);
}

References os::rtos::message_queue::initializer.

os_mqueue_delete()

void os_mqueue_delete

(

os_mqueue_t *

mqueue

)

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 2802 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  delete reinterpret_cast<message_queue*> (mqueue);
}

os_mqueue_destruct()

void os_mqueue_destruct

(

os_mqueue_t *

mqueue

)

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 2757 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  (reinterpret_cast<message_queue&> (*mqueue)).~message_queue ();
}

os_mqueue_get_capacity()

size_t os_mqueue_get_capacity

(

os_mqueue_t *

mqueue

)

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 2931 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  return (reinterpret_cast<message_queue&> (*mqueue)).capacity ();
}

os_mqueue_get_length()

size_t os_mqueue_get_length

(

os_mqueue_t *

mqueue

)

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 2918 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  return (reinterpret_cast<message_queue&> (*mqueue)).length ();
}

os_mqueue_get_msg_size()

size_t os_mqueue_get_msg_size

(

os_mqueue_t *

mqueue

)

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 2944 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  return (reinterpret_cast<message_queue&> (*mqueue)).msg_size ();
}

os_mqueue_get_name()

const char * os_mqueue_get_name

(

os_mqueue_t *

mqueue

)

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 2815 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  return (reinterpret_cast<message_queue&> (*mqueue)).name ();
}

os_mqueue_is_empty()

bool os_mqueue_is_empty

(

os_mqueue_t *

mqueue

)

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 2957 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  return (reinterpret_cast<message_queue&> (*mqueue)).empty ();
}

os_mqueue_is_full()

bool os_mqueue_is_full

(

os_mqueue_t *

mqueue

)

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 2970 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  return (reinterpret_cast<message_queue&> (*mqueue)).full ();
}

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
	)

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 2777 of file os-c-wrapper.cpp.

{
  if (attr == nullptr)
    {
      attr = (const os_mqueue_attr_t*)&message_queue::initializer;
    }
  return reinterpret_cast<os_mqueue_t*> (new message_queue (
      name, msgs, msg_size_bytes, (const message_queue::attributes&)*attr));
}

References os::rtos::message_queue::initializer.

os_mqueue_receive()

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

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 2873 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  return (os_result_t)(reinterpret_cast<message_queue&> (*mqueue))
      .receive (msg, nbytes, mprio);
}

os_mqueue_reset()

os_result_t os_mqueue_reset

(

os_mqueue_t *

mqueue

)

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 2983 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  return (os_result_t)(reinterpret_cast<message_queue&> (*mqueue)).reset ();
}

os_mqueue_send()

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

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 2828 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  return (os_result_t)(reinterpret_cast<message_queue&> (*mqueue))
      .send (msg, nbytes, mprio);
}

References send().

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
	)

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 2903 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  return (os_result_t)(reinterpret_cast<message_queue&> (*mqueue))
      .timed_receive (msg, nbytes, timeout, mprio);
}

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
	)

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 2858 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  return (os_result_t)(reinterpret_cast<message_queue&> (*mqueue))
      .timed_send (msg, nbytes, timeout, mprio);
}

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
	)

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 2888 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  return (os_result_t)(reinterpret_cast<message_queue&> (*mqueue))
      .try_receive (msg, nbytes, mprio);
}

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
	)

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 2843 of file os-c-wrapper.cpp.

{
  assert (mqueue != nullptr);
  return (os_result_t)(reinterpret_cast<message_queue&> (*mqueue))
      .try_send (msg, nbytes, mprio);
}