Message queue services.
[Native RTAI API.]


Detailed Description

Queue services.

Message queueing is a method by which real-time tasks can exchange or pass data through a RTAI-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.

This implementation is based on a zero-copy scheme for message buffers. Message buffer pools are built over Xenomai's heap objects, which in turn provide the needed support for exchanging messages between kernel and user-space using direct memory mapping.


Files

file  queue.c
 This file is part of the RTAI project.

Functions

int rt_queue_create (RT_QUEUE *q, const char *name, size_t poolsize, size_t qlimit, int mode)
 Create a message queue.
int rt_queue_delete (RT_QUEUE *q)
 Delete a message queue.
void * rt_queue_alloc (RT_QUEUE *q, size_t size)
 Allocate a message queue buffer.
int rt_queue_free (RT_QUEUE *q, void *buf)
 Free a message queue buffer.
int rt_queue_send (RT_QUEUE *q, void *buf, size_t size, int mode)
 Send a message to a queue.
ssize_t rt_queue_recv (RT_QUEUE *q, void **bufp, RTIME timeout)
 Receive a message from a queue.
int rt_queue_inquire (RT_QUEUE *q, RT_QUEUE_INFO *info)
 Inquire about a message queue.
int rt_queue_bind (RT_QUEUE *q, const char *name)
 Bind to a shared message queue.
int rt_queue_unbind (RT_QUEUE *q)
 Unbind from a shared message queue.


Function Documentation

void* rt_queue_alloc RT_QUEUE *  q,
size_t  size
 

Allocate a message queue buffer.

This service allocates a message buffer from the queue's internal pool which can be subsequently filled by the caller then passed to rt_queue_send() for sending.

Parameters:
q The descriptor address of the affected queue.
size The requested size in bytes of the buffer. Zero is an acceptable value, meaning that the message will not carry any payload data; the receiver will thus receive a zero-sized message.
Returns:
The address of the allocated message buffer upon success, or NULL if the allocation fails.
Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: never.

int rt_queue_bind RT_QUEUE *  q,
const char *  name
 

Bind to a shared message queue.

This user-space only service retrieves the ubiquitous descriptor of a given shared RTAI message queue identified by its symbolic name. If the queue does not exist on entry, this service blocks the caller until a queue of the given name is created.

Parameters:
name A valid NULL-terminated name which identifies the queue to bind to.
q The address of a queue descriptor retrieved by the operation. Contents of this memory is undefined upon failure.
Returns:
0 is returned upon success. Otherwise:
  • -EFAULT is returned if q or name is referencing invalid memory.

  • -EINTR is returned if rt_task_unblock() has been called for the waiting task before the retrieval has completed.

Environments:

This service can be called from:

  • User-space task (switches to primary mode)

Rescheduling: always unless the request is immediately satisfied.

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 that allows multiple tasks to exchange data through the use of variable-sized messages. A message queue is created empty. Message queues can be local to the kernel space, or shared between kernel and user-space.

Parameters:
q The address of a queue descriptor RTAI will use to store the queue-related data. This descriptor must always be valid while the message queue is active therefore it must be allocated in permanent memory.
name An ASCII string standing for the symbolic name of the queue. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created queue. Shared queues must be given a valid name.
poolsize The size (in bytes) of the message buffer pool which is going to be pre-allocated to the queue. Message buffers will be claimed and released to this pool. The buffer pool memory is not extensible, so this value must be compatible with the highest message pressure that could be expected.
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 specify an unlimited amount.
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.

  • Q_SHARED causes the queue to be sharable between kernel and user-space tasks. Otherwise, the new queue is only available for kernel-based usage. This flag is implicitely set when the caller is running in user-space. This feature requires the real-time support in user-space to be configured in (CONFIG_OPT_RTAI_FUSION).

  • Q_DMA causes the buffer pool associated to the queue to be allocated in physically contiguous memory, suitable for DMA operations with I/O devices. A 128Kb limit exists for poolsize when this flag is passed.

Returns:
0 is returned upon success. Otherwise:
  • -EEXIST is returned if the name is already in use by some registered object.

  • -EINVAL is returned if poolsize is null, greater than the system limit, or name is null or empty for a shared queue.

  • -ENOMEM is returned if not enough system memory is available to create the queue. Additionally, and if Q_SHARED has been passed in mode, errors while mapping the buffer pool in the caller's address space might beget this return code too.

  • -ENOSYS is returned if mode specifies Q_SHARED, but the real-time support in user-space is unavailable.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • User-space task

Rescheduling: possible.

int rt_queue_delete RT_QUEUE *  q  ) 
 

Delete a message queue.

Destroy a message queue and release all the tasks currently pending on it. A queue exists in the system since rt_queue_create() has been called to create it, so this service must be called in order to destroy it afterwards.

Parameters:
q The descriptor address of the affected queue.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if q is not a message queue descriptor.

  • -EIDRM is returned if q is a deleted queue descriptor.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • User-space task

Rescheduling: possible.

int rt_queue_free RT_QUEUE *  q,
void *  buf
 

Free a message queue buffer.

This service releases a message buffer returned by rt_queue_recv() to the queue's internal pool.

Parameters:
q The descriptor address of the affected queue.
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:
0 is returned upon success, or -EINVAL if buf is not a valid message buffer previously allocated by the rt_queue_alloc() service.
Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: never.

int rt_queue_inquire RT_QUEUE *  q,
RT_QUEUE_INFO *  info
 

Inquire about a message queue.

Return various information about the status of a given queue.

Parameters:
q The descriptor address of the inquired queue.
info The address of a structure the queue information will be written to.
Returns:
0 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 message queue descriptor.

  • -EIDRM is returned if q is a deleted queue descriptor.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: never.

ssize_t rt_queue_recv RT_QUEUE *  q,
void **  bufp,
RTIME  timeout
 

Receive a message from a queue.

This service retrieves the next message available from the given queue. Unless otherwise specified, the caller is blocked for a given amount of time if no message is immediately available on entry.

Parameters:
q The descriptor address of the message queue to receive from.
bufp A pointer to a memory location which will be written upon success with the address of the received message. Once consumed, the message space should be freed using rt_queue_free().
timeout The number of clock ticks to wait for some message to arrive (see note). Passing TM_INFINITE causes the caller to block indefinitely until some message is eventually available. Passing TM_NONBLOCK causes the service to return immediately without waiting if no message is available on entry.
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(). Otherwise:
  • -EINVAL is returned if q is not a message queue descriptor.

  • -EIDRM is returned if q is a deleted queue descriptor.

  • -ETIMEDOUT is returned if timeout is different from TM_NONBLOCK and no message is available within the specified amount of time.

  • -EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and no message is immediately available on entry.

  • -EINTR is returned if rt_task_unblock() has been called for the waiting task before any data was available.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine only if timeout is equal to TM_NONBLOCK.

  • Kernel-based task
  • User-space task (switches to primary mode)

Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation.

Note:
This service is sensitive to the current operation mode of the system timer, as defined by the rt_timer_start() service. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.

int rt_queue_send RT_QUEUE *  q,
void *  buf,
size_t  size,
int  mode
 

Send a message to a queue.

This service sends a complete message to a given queue.

Parameters:
q The descriptor address of the message queue to send to.
buf The address of the message to be sent. The message space 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 size in bytes of the message. 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.

  • -EIDRM is returned if q is a deleted queue descriptor.

  • -ENOMEM is returned if queuing the message would exceed the limit defined for the queue at creation.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: possible.

int rt_queue_unbind RT_QUEUE *  q  ) 
 

Unbind from a shared message queue.

This user-space only service unbinds the calling task from the message queue object previously retrieved by a call to rt_queue_bind().

Unbinding from a message queue when it is no more needed is especially important in order to properly release the mapping resources used to attach the shared queue memory to the caller's address space.

Parameters:
q The address of a queue descriptor to unbind from.
Returns:
0 is always returned.
This service can be called from:

  • User-space task.

Rescheduling: never.


Generated on Mon Dec 13 09:49:49 2004 for RTAI API by  doxygen 1.3.9.1