POSIXish condition variable mechanism.
More...
|
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...
|
|
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.
◆ 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
-
cond | The address of a condition variable descriptor filled in by the operation. Contents of this memory is undefined upon failure. |
name | A 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(). |
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_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
-
cond | The condition variable descriptor. |
- Returns
- Zero is returned upon success. Otherwise:
- -EINVAL is returned if cond is not a valid condition variable descriptor.
- 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
-
cond | The address of a condition variable 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 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 asynchronous context.
- Tags
- 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
-
cond | The 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
- mode-unrestricted, switch-secondary
◆ rt_cond_inquire()
Query condition variable status.
This routine returns the status information about the specified condition variable.
- Parameters
-
cond | The condition variable descriptor. |
info | A 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
- 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
-
cond | The condition variable descriptor. |
- Returns
- Zero is returned upon success. Otherwise:
- -EINVAL is returned if cond is not a valid condition variable descriptor.
- Tags
- unrestricted, switch-primary
◆ rt_cond_unbind()
int rt_cond_unbind |
( |
RT_COND * |
cond | ) |
|
Unbind from a condition variable.
- Parameters
-
cond | The 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
- 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
-
cond | The condition variable descriptor. |
mutex | The address of the mutex serializing the access to the shared data. |
timeout | A delay expressed in clock ticks. |
- 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
-
cond | The condition variable descriptor. |
mutex | The address of the mutex serializing the access to the shared data. |
abs_timeout | An 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. |
- 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
- 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
-
cond | The condition variable descriptor. |
mutex | The address of the mutex serializing the access to the shared data. |
abs_timeout | An absolute date expressed in clock ticks. |
- Tags
- xthread-only, switch-primary