Message queue services

real-time IPC mechanism for sending messages of arbitrary size More...

Collaboration diagram for Message queue services:

Data Structures
struct	RT_QUEUE_INFO
	Queue status descriptor. More...

Macros
#define	Q_PRIO   0x1 /* Pend by task priority order. */
	Creation flags. More...

Functions
int	rt_queue_create (RT_QUEUE *queue, const char *name, size_t poolsize, size_t qlimit, int mode)
	Create a message queue. More...
int	rt_queue_delete (RT_QUEUE *queue)
	Delete a message queue. More...
void *	rt_queue_alloc (RT_QUEUE *queue, size_t size)
	Allocate a message buffer. More...
int	rt_queue_free (RT_QUEUE *queue, void *buf)
	Free a message buffer. More...
int	rt_queue_send (RT_QUEUE *queue, const void *buf, size_t size, int mode)
	Send a message to a queue. More...
ssize_t	rt_queue_receive_timed (RT_QUEUE *queue, void **bufp, const struct timespec *abs_timeout)
	Receive a message from a queue (with absolute timeout date). More...
static ssize_t	rt_queue_receive_until (RT_QUEUE *queue, void **bufp, RTIME timeout)
	Receive from a queue (with absolute scalar timeout). More...
static ssize_t	rt_queue_receive (RT_QUEUE *queue, void **bufp, RTIME timeout)
	Receive from a queue (with relative scalar timeout). More...
ssize_t	rt_queue_read_timed (RT_QUEUE *queue, void *buf, size_t size, const struct timespec *abs_timeout)
	Read from a queue. More...
static ssize_t	rt_queue_read_until (RT_QUEUE *queue, void *buf, size_t size, RTIME timeout)
	Read from a queue (with absolute scalar timeout). More...
static ssize_t	rt_queue_read (RT_QUEUE *queue, void *buf, size_t size, RTIME timeout)
	Read from a queue (with relative scalar timeout). More...
int	rt_queue_flush (RT_QUEUE *queue)
	Flush pending messages from a queue. More...
int	rt_queue_inquire (RT_QUEUE *queue, RT_QUEUE_INFO *info)
	Query queue status. More...
int	rt_queue_bind (RT_QUEUE *queue, const char *name, RTIME timeout)
	Bind to a message queue. More...
int	rt_queue_unbind (RT_QUEUE *queue)
	Unbind from a message queue. More...

Detailed Description

real-time IPC mechanism for sending messages of arbitrary size

Message queueing is a method by which real-time tasks can exchange or pass data through a Xenomai-managed queue of messages. Messages can vary in length and be assigned different types or usages. A message queue can be created by one task and used by multiple tasks that send and/or receive messages to the queue.

Macro Definition Documentation

Q_PRIO

#define Q_PRIO   0x1 /* Pend by task priority order. */

Creation flags.

Referenced by rt_queue_create().

Function Documentation

rt_queue_alloc()

void * rt_queue_alloc	(	RT_QUEUE *	q,
		size_t	size
	)

Allocate a message buffer.

This service allocates a message buffer from the queue's internal pool. This buffer can be filled in with payload information, prior enqueuing it by a call to rt_queue_send(). When used in pair, these services provide a zero-copy interface for sending messages.

Parameters

q	The queue descriptor.
size	The requested size in bytes of the buffer. Zero is an acceptable value, which means that the message conveys no payload; in this case, the receiver will get a zero-sized message.

Returns

The address of the allocated buffer upon success, or NULL if the call fails.

Tags

unrestricted, switch-primary

rt_queue_bind()

int rt_queue_bind	(	RT_QUEUE *	q,
		const char *	name,
		RTIME	timeout
	)

Bind to a message queue.

This routine creates a new descriptor to refer to an existing message queue identified by its symbolic name. If the object does not exist on entry, the caller may block until a queue of the given name is created.

Parameters

q	The address of a queue descriptor filled in by the operation. Contents of this memory is undefined upon failure.
name	A valid NULL-terminated name which identifies the queue to bind to. This string should match the object name argument passed to rt_queue_create().
timeout	The number of clock ticks to wait for the registration to occur (see note). Passing TM_INFINITE causes the caller to block indefinitely until the object is registered. Passing TM_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry.

Returns

Zero is returned upon success. Otherwise:

• -EINTR is returned if rt_task_unblock() was called for the current task before the retrieval has completed.
• -EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the searched object is not registered on entry.
• -ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.
• -EPERM is returned if this service should block, but was not called from a Xenomai thread.

Tags

xthread-nowait, switch-primary

Note

The timeout value is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

rt_queue_create()

int rt_queue_create	(	RT_QUEUE *	q,
		const char *	name,
		size_t	poolsize,
		size_t	qlimit,
		int	mode
	)

Create a message queue.

Create a message queue object which allows multiple tasks to exchange data through the use of variable-sized messages. A message queue is created empty.

Parameters

q	The address of a queue descriptor which can be later used to identify uniquely the created object, upon success of this call.
name	An ASCII string standing for the symbolic name of the queue. When non-NULL and non-empty, a copy of this string is used for indexing the created queue into the object registry.
poolsize	The size (in bytes) of the message buffer pool to be pre-allocated for holding messages. Message buffers will be claimed and released to this pool. The buffer pool memory cannot be extended. See note.
qlimit	This parameter allows to limit the maximum number of messages which can be queued at any point in time, sending to a full queue begets an error. The special value Q_UNLIMITED can be passed to disable the limit check.
mode	The queue creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new queue:

• Q_FIFO makes tasks pend in FIFO order on the queue for consuming messages.
• Q_PRIO makes tasks pend in priority order on the queue.

Returns

Zero is returned upon success. Otherwise:

• -EINVAL is returned if mode is invalid or poolsize is zero.
• -ENOMEM is returned if the system fails to get memory from the main heap in order to create the queue.
• -EEXIST is returned if the name is conflicting with an already registered queue.
• -EPERM is returned if this service was called from an invalid context, e.g. interrupt or non-Xenomai thread.

Tags

xthread-only, mode-unrestricted, switch-secondary

Note

Queues can be shared by multiple processes which belong to the same Xenomai session.

Each message pending into the queue consumes four long words plus the actual payload size, aligned to the next long word boundary. e.g. a 6 byte message on a 32 bit platform would require 24 bytes of storage into the pool.

When qlimit is given (i.e. different from Q_UNLIMITED), this overhead is accounted for automatically, so that qlimit messages of poolsize / qlimit bytes can be stored into the pool concurrently. Otherwise, poolsize is increased by 5% internally to cope with such overhead.

References Q_PRIO.

rt_queue_delete()

int rt_queue_delete

(

RT_QUEUE *

q

)

Delete a message queue.

This routine deletes a queue object previously created by a call to rt_queue_create(). All resources attached to that queue are automatically released, including all pending messages.

Parameters

q	The queue descriptor.

Returns

Zero is returned upon success. Otherwise:

• -EINVAL is returned if q is not a valid queue descriptor.
• -EPERM is returned if this service was called from an asynchronous context.

Tags

mode-unrestricted, switch-secondary

rt_queue_flush()

int rt_queue_flush

(

RT_QUEUE *

q

)

Flush pending messages from a queue.

This routine flushes all messages currently pending in a queue, releasing all message buffers appropriately.

Parameters

q	The queue descriptor.

Returns

Zero is returned upon success. Otherwise:

• -EINVAL is returned if q is not a valid queue descriptor.

Tags

unrestricted, switch-primary

rt_queue_free()

int rt_queue_free	(	RT_QUEUE *	q,
		void *	buf
	)

Free a message buffer.

This service releases a message buffer to the queue's internal pool.

Parameters

q	The queue descriptor.
buf	The address of the message buffer to free. Even zero-sized messages carrying no payload data must be freed, since they are assigned a valid memory space to store internal information.

Returns

Zero is returned upon success, or -EINVAL if buf is not a valid message buffer previously allocated by the rt_queue_alloc() service, or the caller did not get ownership of the message through a successful return from rt_queue_receive().

Tags

unrestricted, switch-primary

rt_queue_inquire()

int rt_queue_inquire	(	RT_QUEUE *	q,
		RT_QUEUE_INFO *	info
	)

Query queue status.

This routine returns the status information about the specified queue.

Parameters

q	The queue descriptor.
info	A pointer to the return buffer" to copy the information to.

Returns

Zero is returned and status information is written to the structure pointed at by info upon success. Otherwise:

• -EINVAL is returned if q is not a valid queue descriptor.

Tags

unrestricted, switch-primary

rt_queue_read()

ssize_t rt_queue_read ( RT_QUEUE *  q, void *  buf, size_t  size, RTIME  timeout  )

inlinestatic

Read from a queue (with relative scalar timeout).

This routine is a variant of rt_queue_read_timed() accepting a relative timeout specification expressed as a scalar value.

Parameters

q	The queue descriptor.
buf	A pointer to a memory area which will be written upon success with the received message payload.
size	The length in bytes of the memory area pointed to by buf.
timeout	A delay expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until a message is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case no message is available.

Tags

xthread-nowait, switch-primary

rt_queue_read_timed()

ssize_t rt_queue_read_timed	(	RT_QUEUE *	q,
		void *	buf,
		size_t	size,
		const struct timespec *	abs_timeout
	)

Read from a queue.

This service reads the next available message from a given queue.

Parameters

q	The queue descriptor.
buf	A pointer to a memory area which will be written upon success with the received message payload. The internal message buffer conveying the data is automatically freed by this call. If –enable-pshared is enabled in the configuration, buf must have been obtained from the Xenomai memory allocator via xnmalloc() or any service based on it, such as rt_heap_alloc().
size	The length in bytes of the memory area pointed to by buf. Messages larger than size are truncated appropriately.
abs_timeout	An absolute date expressed in clock ticks, specifying a time limit to wait for a message to be available from the queue (see note). Passing NULL causes the caller to block indefinitely until a message is available. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately without blocking in case no message is available.

Returns

The number of bytes copied to buf is returned upon success. Zero is a possible value corresponding to a zero-sized message passed to rt_queue_send() or rt_queue_write(). Otherwise:

• -ETIMEDOUT is returned if abs_timeout is reached before a message arrives.
• -EWOULDBLOCK is returned if abs_timeout is { .tv_sec = 0, .tv_nsec = 0 } and no message is immediately available on entry to the call.
• -EINTR is returned if rt_task_unblock() was called for the current task before a message was available.
• -EINVAL is returned if q is not a valid queue descriptor.
• -EIDRM is returned if q is deleted while the caller was waiting for a message. In such event, q is no more valid upon return of this service.
• -EPERM is returned if this service should block, but was not called from a Xenomai thread.

Tags

xthread-nowait, switch-primary

Note

abs_timeout is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

rt_queue_read_until()

ssize_t rt_queue_read_until ( RT_QUEUE *  q, void *  buf, size_t  size, RTIME  abs_timeout  )

inlinestatic

Read from a queue (with absolute scalar timeout).

This routine is a variant of rt_queue_read_timed() accepting an absolute timeout specification expressed as a scalar value.

Parameters

q	The queue descriptor.
buf	A pointer to a memory area which will be written upon success with the received message payload.
size	The length in bytes of the memory area pointed to by buf.
abs_timeout	An absolute date expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until a message is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case no message is available.

Tags

xthread-nowait, switch-primary

rt_queue_receive()

ssize_t rt_queue_receive ( RT_QUEUE *  q, void **  bufp, RTIME  timeout  )

inlinestatic

Receive from a queue (with relative scalar timeout).

This routine is a variant of rt_queue_receive_timed() accepting a relative timeout specification expressed as a scalar value.

Parameters

q	The queue descriptor.
bufp	A pointer to a memory location which will be written with the address of the received message.
timeout	A delay expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until a message is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case no message is available.

Tags

xthread-nowait, switch-primary

rt_queue_receive_timed()

ssize_t rt_queue_receive_timed	(	RT_QUEUE *	q,
		void **	bufp,
		const struct timespec *	abs_timeout
	)

Receive a message from a queue (with absolute timeout date).

This service receives the next available message from a given queue.

Parameters

q	The queue descriptor.
bufp	A pointer to a memory location which will be written with the address of the received message, upon success. Once consumed, the message space should be freed using rt_queue_free().
abs_timeout	An absolute date expressed in clock ticks, specifying a time limit to wait for a message to be available from the queue (see note). Passing NULL causes the caller to block indefinitely until a message is available. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately without blocking in case no message is available.

Returns

The number of bytes available from the received message is returned upon success. Zero is a possible value corresponding to a zero-sized message passed to rt_queue_send() or rt_queue_write(). Otherwise:

• -ETIMEDOUT is returned if abs_timeout is reached before a message arrives.
• -EWOULDBLOCK is returned if abs_timeout is { .tv_sec = 0, .tv_nsec = 0 } and no message is immediately available on entry to the call.
• -EINTR is returned if rt_task_unblock() was called for the current task before a message was available.
• -EINVAL is returned if q is not a valid queue descriptor.
• -EIDRM is returned if q is deleted while the caller was waiting for a message. In such event, q is no more valid upon return of this service.
• -EPERM is returned if this service should block, but was not called from a Xenomai thread.

Tags

xthread-nowait, switch-primary

Note

abs_timeout is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

rt_queue_receive_until()

ssize_t rt_queue_receive_until ( RT_QUEUE *  q, void **  bufp, RTIME  abs_timeout  )

inlinestatic

Receive from a queue (with absolute scalar timeout).

This routine is a variant of rt_queue_receive_timed() accepting an absolute timeout specification expressed as a scalar value.

Parameters

q	The queue descriptor.
bufp	A pointer to a memory location which will be written with the address of the received message.
abs_timeout	An absolute date expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until a message is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case no message is available.

Tags

xthread-nowait, switch-primary

rt_queue_send()

int rt_queue_send	(	RT_QUEUE *	q,
		const void *	buf,
		size_t	size,
		int	mode
	)

Send a message to a queue.

This service sends a complete message to a given queue. The message must have been allocated by a previous call to rt_queue_alloc().

Parameters

q	The queue descriptor.
buf	The address of the message buffer to be sent. The message buffer must have been allocated using the rt_queue_alloc() service. Once passed to rt_queue_send(), the memory pointed to by buf is no more under the control of the sender and thus should not be referenced by it anymore; deallocation of this memory must be handled on the receiving side.
size	The actual size in bytes of the message, which may be lower than the allocated size for the buffer obtained from rt_queue_alloc(). Zero is a valid value, in which case an empty message will be sent.
mode	A set of flags affecting the operation:

• Q_URGENT causes the message to be prepended to the message queue, ensuring a LIFO ordering.
• Q_NORMAL causes the message to be appended to the message queue, ensuring a FIFO ordering.
• Q_BROADCAST causes the message to be sent to all tasks currently waiting for messages. The message is not copied; a reference count is maintained instead so that the message will remain valid until the last receiver releases its own reference using rt_queue_free(), after which the message space will be returned to the queue's internal pool.

Returns

Upon success, this service returns the number of receivers which got awaken as a result of the operation. If zero is returned, no task was waiting on the receiving side of the queue, and the message has been enqueued. Upon error, one of the following error codes is returned:

• -EINVAL is returned if q is not a message queue descriptor, mode is invalid, or buf is NULL.
• -ENOMEM is returned if queuing the message would exceed the limit defined for the queue at creation.

Tags

unrestricted, switch-primary

rt_queue_unbind()

int rt_queue_unbind

(

RT_QUEUE *

q

)

Unbind from a message queue.

Parameters

q	The queue descriptor.

This routine releases a previous binding to a message queue. After this call has returned, the descriptor is no more valid for referencing this object.

Tags

thread-unrestricted