Xenomai  3.0.8
Condition variable services

POSIXish condition variable mechanism. More...

Collaboration diagram for Condition variable services:

Data Structures

struct  RT_COND_INFO
 Condition variable status descriptor. More...
 

Functions

int rt_cond_create (RT_COND *cond, const char *name)
 Create a condition variable. More...
 
int rt_cond_delete (RT_COND *cond)
 Delete a condition variable. More...
 
int rt_cond_signal (RT_COND *cond)
 Signal a condition variable. More...
 
int rt_cond_broadcast (RT_COND *cond)
 Broadcast a condition variable. More...
 
int rt_cond_wait_timed (RT_COND *cond, RT_MUTEX *mutex, const struct timespec *abs_timeout)
 Wait on a condition variable. More...
 
static int rt_cond_wait_until (RT_COND *cond, RT_MUTEX *mutex, RTIME timeout)
 Wait on a condition variable (with absolute scalar timeout). More...
 
static int rt_cond_wait (RT_COND *cond, RT_MUTEX *mutex, RTIME timeout)
 Wait on a condition variable (with relative scalar timeout). More...
 
int rt_cond_inquire (RT_COND *cond, RT_COND_INFO *info)
 Query condition variable status. More...
 
int rt_cond_bind (RT_COND *cond, const char *name, RTIME timeout)
 Bind to a condition variable. More...
 
int rt_cond_unbind (RT_COND *cond)
 Unbind from a condition variable. More...
 

Detailed Description

POSIXish condition variable mechanism.

A condition variable is a synchronization mechanism which allows tasks to suspend execution until some predicate on some arbitrary shared data is satisfied.

The basic operations on conditions are: signal the condition (when the predicate becomes true), and wait for the condition, blocking the task execution until another task signals the condition. A condition variable must always be associated with a mutex, to avoid a well-known race condition where a task prepares to wait on a condition variable and another task signals the condition just before the first task actually waits on it.

Function Documentation

◆ rt_cond_bind()

int rt_cond_bind ( RT_COND *  cond,
const char *  name,
RTIME  timeout 
)

Bind to a condition variable.

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

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

int rt_cond_broadcast ( RT_COND *  cond)

Broadcast a condition variable.

All tasks currently waiting on the condition variable are immediately unblocked.

Parameters
condThe condition variable descriptor.
Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if cond is not a valid condition variable descriptor.
Tags api-tags "unrestricted, switch-primary"

◆ rt_cond_create()

int rt_cond_create ( RT_COND *  cond,
const char *  name 
)

Create a condition variable.

Create a synchronization object which allows tasks to suspend execution until some predicate on shared data is satisfied.

Parameters
condThe address of a condition variable 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 condition variable. When non-NULL and non-empty, a copy of this string is used for indexing the created condition variable into the object registry.
Returns
Zero is returned upon success. Otherwise:
  • -ENOMEM is returned if the system fails to get memory from the main heap in order to create the condition variable.
  • -EEXIST is returned if the name is conflicting with an already registered condition variable.
  • -EPERM is returned if this service was called from an invalid context, e.g. interrupt or non-Xenomai thread.
Tags api-tags "xthread-only, mode-unrestricted, switch-secondary"
Note
Condition variables can be shared by multiple processes which belong to the same Xenomai session.
Attention
If the underlying threading library does not support pthread_condattr_setclock(), timings with Alchemy condition variables will be based on CLOCK_REALTIME, and may therefore be affected by updates to the system date (e.g. NTP). This typically concerns legacy setups based on the linuxthreads library. In the normal case, timings are based on CLOCK_MONOTONIC.

◆ rt_cond_delete()

int rt_cond_delete ( RT_COND *  cond)

Delete a condition variable.

This routine deletes a condition variable object previously created by a call to rt_cond_create().

Parameters
condThe condition variable descriptor.
Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if alarm is not a valid condition variable descriptor.
  • -EPERM is returned if this service was called from an asynchronous context.
  • -EBUSY is returned upon an attempt to destroy the object referenced by cond while it is referenced (for example, while being used in a rt_cond_wait(), rt_cond_wait_timed() or rt_cond_wait_until() by another task).
Tags api-tags "mode-unrestricted, switch-secondary"

◆ rt_cond_inquire()

int rt_cond_inquire ( RT_COND *  cond,
RT_COND_INFO info 
)

Query condition variable status.

This routine returns the status information about the specified condition variable.

Parameters
condThe condition variable descriptor.
infoA pointer to the returnbuffer" 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 cond is not a valid condition variable descriptor.
Tags api-tags "unrestricted, switch-primary"

◆ rt_cond_signal()

int rt_cond_signal ( RT_COND *  cond)

Signal a condition variable.

If the condition variable cond is pended, this routine immediately unblocks the first waiting task (by queuing priority order).

Parameters
condThe condition variable descriptor.
Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if cond is not a valid condition variable descriptor.
Tags api-tags "unrestricted, switch-primary"

◆ rt_cond_unbind()

int rt_cond_unbind ( RT_COND *  cond)

Unbind from a condition variable.

Parameters
condThe condition variable descriptor.

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

Tags api-tags "thread-unrestricted"

◆ rt_cond_wait()

int rt_cond_wait ( RT_COND *  cond,
RT_MUTEX *  mutex,
RTIME  timeout 
)
inlinestatic

Wait on a condition variable (with relative scalar timeout).

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

Parameters
condThe condition variable descriptor.
mutexThe address of the mutex serializing the access to the shared data.
timeoutA delay expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely. Passing TM_NONBLOCK causes the caller to return immediately without block.
Tags api-tags "xthread-only, switch-primary"

◆ rt_cond_wait_timed()

int rt_cond_wait_timed ( RT_COND *  cond,
RT_MUTEX *  mutex,
const struct timespec *  abs_timeout 
)

Wait on a condition variable.

This service atomically releases the mutex and blocks the calling task, until the condition variable cond is signaled or a timeout occurs, whichever comes first. The mutex is re-acquired before returning from this service.

Parameters
condThe condition variable descriptor.
mutexThe address of the mutex serializing the access to the shared data.
abs_timeoutAn absolute date expressed in clock ticks, specifying a time limit to wait for the condition variable to be signaled (see note). Passing NULL causes the caller to block indefinitely. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the caller to return immediately without block.
Returns
Zero is returned upon success. Otherwise:
  • -ETIMEDOUT is returned if abs_timeout is reached before the condition variable is signaled.
  • -EWOULDBLOCK is returned if abs_timeout is { .tv_sec = 0, .tv_nsec = 0 } .
  • -EINTR is returned if rt_task_unblock() was called for the current task.
  • -EINVAL is returned if cond is not a valid condition variable descriptor.
  • -EIDRM is returned if cond is deleted while the caller was waiting on the condition variable. In such event, cond 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 api-tags "xthread-only, 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_cond_wait_until()

int rt_cond_wait_until ( RT_COND *  cond,
RT_MUTEX *  mutex,
RTIME  abs_timeout 
)
inlinestatic

Wait on a condition variable (with absolute scalar timeout).

This routine is a variant of rt_cond_wait_timed() accepting an abs_timeout specification expressed as a scalar value.

Parameters
condThe condition variable descriptor.
mutexThe address of the mutex serializing the access to the shared data.
abs_timeoutAn absolute date expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely. Passing TM_NONBLOCK causes the caller to return immediately without block.
Tags api-tags "xthread-only, switch-primary"