Xenomai  3.1
Buffer services

Lightweight FIFO IPC mechanism. More...

Collaboration diagram for Buffer services:

Data Structures

struct  RT_BUFFER_INFO
 Buffer status descriptor. More...
 

Macros

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

Functions

int rt_buffer_create (RT_BUFFER *bf, const char *name, size_t bufsz, int mode)
 
Create an IPC buffer. More...
 
int rt_buffer_delete (RT_BUFFER *bf)
 
Delete an IPC buffer. More...
 
ssize_t rt_buffer_write_timed (RT_BUFFER *bf, const void *ptr, size_t size, const struct timespec *abs_timeout)
 
Write to an IPC buffer. More...
 
static ssize_t rt_buffer_write_until (RT_BUFFER *bf, const void *ptr, size_t size, RTIME timeout)
 
Write to an IPC buffer (with absolute scalar timeout). More...
 
static ssize_t rt_buffer_write (RT_BUFFER *bf, const void *ptr, size_t size, RTIME timeout)
 
Write to an IPC buffer (with relative scalar timeout). More...
 
ssize_t rt_buffer_read_timed (RT_BUFFER *bf, void *ptr, size_t size, const struct timespec *abs_timeout)
 
Read from an IPC buffer. More...
 
static ssize_t rt_buffer_read_until (RT_BUFFER *bf, void *ptr, size_t size, RTIME timeout)
 
Read from an IPC buffer (with absolute scalar timeout). More...
 
static ssize_t rt_buffer_read (RT_BUFFER *bf, void *ptr, size_t size, RTIME timeout)
 
Read from an IPC buffer (with relative scalar timeout). More...
 
int rt_buffer_clear (RT_BUFFER *bf)
 
Clear an IPC buffer. More...
 
int rt_buffer_inquire (RT_BUFFER *bf, RT_BUFFER_INFO *info)
 
Query buffer status. More...
 
int rt_buffer_bind (RT_BUFFER *bf, const char *name, RTIME timeout)
 
Bind to an IPC buffer. More...
 
int rt_buffer_unbind (RT_BUFFER *bf)
 
Unbind from an IPC buffer. More...
 

Detailed Description

Lightweight FIFO IPC mechanism.

A buffer is a lightweight IPC mechanism, implementing a fast, one-way producer-consumer data path. All messages written are buffered in a single memory area in strict FIFO order, until read either in blocking or non-blocking mode.

Message are always atomically handled on the write side (i.e. no interleave, no short writes), whilst only complete messages are normally returned to the read side. However, short reads may happen under a well-defined situation (see note in rt_buffer_read()), albeit they can be fully avoided by proper use of the buffer.

Macro Definition Documentation

◆ B_PRIO

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

Creation flags.

Referenced by rt_buffer_create().

Function Documentation

◆ rt_buffer_bind()

int rt_buffer_bind ( RT_BUFFER *  bf,
const char *  name,
RTIME  timeout 
)


Bind to an IPC buffer.

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

Parameters
bfThe address of a buffer descriptor filled in by the operation. Contents of this memory is undefined upon failure.
nameA valid NULL-terminated name which identifies the buffer to bind to. This string should match the object name argument passed to rt_buffer_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_buffer_clear()

int rt_buffer_clear ( RT_BUFFER *  bf)


Clear an IPC buffer.

This routine empties a buffer from any data.

Parameters
bfThe buffer descriptor.
Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if bf is not a valid buffer descriptor.
Tags
unrestricted, switch-primary

◆ rt_buffer_create()

int rt_buffer_create ( RT_BUFFER *  bf,
const char *  name,
size_t  bufsz,
int  mode 
)


Create an IPC buffer.

This routine creates an IPC object that allows tasks to send and receive data asynchronously via a memory buffer. Data may be of an arbitrary length, albeit this IPC is best suited for small to medium-sized messages, since data always have to be copied to the buffer during transit. Large messages may be more efficiently handled by message queues (RT_QUEUE).

Parameters
bfThe address of a buffer 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 buffer. When non-NULL and non-empty, a copy of this string is used for indexing the created buffer into the object registry.
bufszThe size of the buffer space available to hold data. The required memory is obtained from the main heap.
modeThe buffer creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new buffer:
  • B_FIFO makes tasks pend in FIFO order for reading data from the buffer.
  • B_PRIO makes tasks pend in priority order for reading data from the buffer.

This parameter also applies to tasks blocked on the buffer's write side (see rt_buffer_write()).

Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if mode is invalid or bufsz is zero.
  • -ENOMEM is returned if the system fails to get memory from the main heap in order to create the buffer.
  • -EEXIST is returned if the name is conflicting with an already registered buffer.
  • -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
Buffers can be shared by multiple processes which belong to the same Xenomai session.

References B_PRIO.

◆ rt_buffer_delete()

int rt_buffer_delete ( RT_BUFFER *  bf)


Delete an IPC buffer.

This routine deletes a buffer object previously created by a call to rt_buffer_create().

Parameters
bfThe buffer descriptor.
Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if bf is not a valid buffer descriptor.
  • -EPERM is returned if this service was called from an asynchronous context.
Tags
mode-unrestricted, switch-secondary

◆ rt_buffer_inquire()

int rt_buffer_inquire ( RT_BUFFER *  bf,
RT_BUFFER_INFO info 
)


Query buffer status.

This routine returns the status information about the specified buffer.

Parameters
bfThe buffer 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 bf is not a valid buffer descriptor.
Tags
unrestricted, switch-primary

◆ rt_buffer_read()

ssize_t rt_buffer_read ( RT_BUFFER *  bf,
void *  ptr,
size_t  len,
RTIME  timeout 
)
inlinestatic


Read from an IPC buffer (with relative scalar timeout).

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

Parameters
bfThe buffer descriptor.
ptrA pointer to a memory area which will be written upon success with the received data.
lenThe length in bytes of the memory area pointed to by ptr.
timeoutA delay expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until enough data is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case not enough data is available.
Tags
xthread-nowait, switch-primary

◆ rt_buffer_read_timed()

ssize_t rt_buffer_read_timed ( RT_BUFFER *  bf,
void *  ptr,
size_t  len,
const struct timespec *  abs_timeout 
)


Read from an IPC buffer.

This routine reads the next message from the specified buffer. If no message is available on entry, the caller is allowed to block until enough data is written to the buffer, or a timeout elapses.

Parameters
bfThe buffer descriptor.
ptrA pointer to a memory area which will be written upon success with the received data.
lenThe length in bytes of the memory area pointed to by ptr. Under normal circumstances, rt_buffer_read_timed() only returns entire messages as specified by the len argument, or an error value. However, short reads are allowed when a potential deadlock situation is detected (see note below).
abs_timeoutAn absolute date expressed in clock ticks, specifying a time limit to wait for a message to be available from the buffer (see note). Passing NULL causes the caller to block indefinitely until enough data is available. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately without blocking in case not enough data is available.
Returns
The number of bytes read from the buffer is returned upon success. Otherwise:
  • -ETIMEDOUT is returned if abs_timeout is reached before a complete message arrives.
  • -EWOULDBLOCK is returned if abs_timeout is { .tv_sec = 0, .tv_nsec = 0 } and not enough data is immediately available on entry to form a complete message.
  • -EINTR is returned if rt_task_unblock() was called for the current task before enough data became available to form a complete message.
  • -EINVAL is returned if bf is not a valid buffer descriptor, or len is greater than the actual buffer length.
  • -EIDRM is returned if bf is deleted while the caller was waiting for data. In such event, bf 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.
Note
A short read (i.e. fewer bytes returned than requested by len) may happen whenever a pathological use of the buffer is encountered. This condition only arises when the system detects that one or more writers are waiting for sending data, while a reader would have to wait for receiving a complete message at the same time. For instance, consider the following sequence, involving a 1024-byte buffer (bf) and two threads:

writer thread > rt_write_buffer(&bf, ptr, 1, TM_INFINITE); (one byte to read, 1023 bytes available for sending) writer thread > rt_write_buffer(&bf, ptr, 1024, TM_INFINITE); (writer blocks - no space for another 1024-byte message) reader thread > rt_read_buffer(&bf, ptr, 1024, TM_INFINITE); (short read - a truncated (1-byte) message is returned)

In order to prevent both threads to wait for each other indefinitely, a short read is allowed, which may be completed by a subsequent call to rt_buffer_read() or rt_buffer_read_until(). If that case arises, thread priorities, buffer and/or message lengths should likely be fixed, in order to eliminate such condition.

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_buffer_read_until()

ssize_t rt_buffer_read_until ( RT_BUFFER *  bf,
void *  ptr,
size_t  len,
RTIME  abs_timeout 
)
inlinestatic


Read from an IPC buffer (with absolute scalar timeout).

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

Parameters
bfThe buffer descriptor.
ptrA pointer to a memory area which will be written upon success with the received data.
lenThe length in bytes of the memory area pointed to by ptr.
abs_timeoutAn absolute date expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until enough data is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case not enough data is available.
Tags
xthread-nowait, switch-primary

◆ rt_buffer_unbind()

int rt_buffer_unbind ( RT_BUFFER *  bf)


Unbind from an IPC buffer.

Parameters
bfThe buffer descriptor.

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

Tags
thread-unrestricted

◆ rt_buffer_write()

ssize_t rt_buffer_write ( RT_BUFFER *  bf,
const void *  ptr,
size_t  len,
RTIME  timeout 
)
inlinestatic


Write to an IPC buffer (with relative scalar timeout).

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

Parameters
bfThe buffer descriptor.
ptrThe address of the message data to be written to the buffer.
lenThe length in bytes of the message data.
timeoutA delay expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until enough buffer space is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case of buffer space shortage.
Tags
xthread-nowait, switch-primary

◆ rt_buffer_write_timed()

ssize_t rt_buffer_write_timed ( RT_BUFFER *  bf,
const void *  ptr,
size_t  len,
const struct timespec *  abs_timeout 
)


Write to an IPC buffer.

This routine writes a message to the specified buffer. If not enough buffer space is available on entry to hold the message, the caller is allowed to block until enough room is freed, or a timeout elapses, whichever comes first.

Parameters
bfThe buffer descriptor.
ptrThe address of the message data to be written to the buffer.
lenThe length in bytes of the message data. Zero is a valid value, in which case the buffer is left untouched, and zero is returned to the caller.
abs_timeoutAn absolute date expressed in clock ticks, specifying a time limit to wait for enough buffer space to be available to hold the message (see note). Passing NULL causes the caller to block indefinitely until enough buffer space is available. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately without blocking in case of buffer space shortage.
Returns
The number of bytes written to the buffer is returned upon success. Otherwise:
  • -ETIMEDOUT is returned if the absolute abs_timeout date is reached before enough buffer space is available to hold the message.
  • -EWOULDBLOCK is returned if abs_timeout is { .tv_sec = 0, .tv_nsec = 0 } and no buffer space is immediately available on entry to hold the message.
  • -EINTR is returned if rt_task_unblock() was called for the current task before enough buffer space became available to hold the message.
  • -EINVAL is returned if bf is not a valid buffer descriptor, or len is greater than the actual buffer length.
  • -EIDRM is returned if bf is deleted while the caller was waiting for buffer space. In such event, bf 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_buffer_write_until()

ssize_t rt_buffer_write_until ( RT_BUFFER *  bf,
const void *  ptr,
size_t  len,
RTIME  abs_timeout 
)
inlinestatic


Write to an IPC buffer (with absolute scalar timeout).

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

Parameters
bfThe buffer descriptor.
ptrThe address of the message data to be written to the buffer.
lenThe length in bytes of the message data.
abs_timeoutAn absolute date expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until enough buffer space is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case of buffer space shortage.
Tags
xthread-nowait, switch-primary