Xenomai  3.1
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
qThe queue descriptor.
sizeThe 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
qThe address of a queue descriptor filled in by the operation. Contents of this memory is undefined upon failure.
nameA valid NULL-terminated name which identifies the queue to bind to. This string should match the object name argument passed to rt_queue_create().
timeoutThe 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
qThe address of a queue descriptor which can be later used to identify uniquely the created object, upon success of this call.
nameAn 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.
poolsizeThe 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.
qlimitThis 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.
modeThe 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
qThe 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
qThe 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
qThe queue descriptor.
bufThe 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
qThe queue descriptor.
infoA 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
qThe queue descriptor.
bufA pointer to a memory area which will be written upon success with the received message payload.
sizeThe length in bytes of the memory area pointed to by buf.
timeoutA 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
qThe queue descriptor.
bufA 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().
sizeThe length in bytes of the memory area pointed to by buf. Messages larger than size are truncated appropriately.
abs_timeoutAn 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
qThe queue descriptor.
bufA pointer to a memory area which will be written upon success with the received message payload.
sizeThe length in bytes of the memory area pointed to by buf.
abs_timeoutAn 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
qThe queue descriptor.
bufpA pointer to a memory location which will be written with the address of the received message.
timeoutA 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
qThe queue descriptor.
bufpA 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_timeoutAn 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
qThe queue descriptor.
bufpA pointer to a memory location which will be written with the address of the received message.
abs_timeoutAn 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
qThe queue descriptor.
bufThe 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.
sizeThe 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.
modeA 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
qThe 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