Condition variable services.
[Native RTAI API.]


Detailed Description

Condition variable services.

A condition condition variable is a synchronization object that allows tasks to suspend execution until some predicate on 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.


Files

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

Functions

int rt_cond_create (RT_COND *cond, const char *name)
 Create a condition variable.
int rt_cond_delete (RT_COND *cond)
 Delete a condition variable.
int rt_cond_signal (RT_COND *cond)
 Signal a condition variable.
int rt_cond_broadcast (RT_COND *cond)
 Broadcast a condition variable.
int rt_cond_wait (RT_COND *cond, RT_MUTEX *mutex, RTIME timeout)
 Wait on a condition.
int rt_cond_inquire (RT_COND *cond, RT_COND_INFO *info)
 Inquire about a condition variable.


Function Documentation

int rt_cond_broadcast RT_COND *  cond  ) 
 

Broadcast a condition variable.

If the condition variable is pended, all tasks currently waiting on it are immediately unblocked.

Parameters:
cond The descriptor address of the affected condition variable.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if cond is not a condition variable descriptor.

  • -EIDRM is returned if cond is a deleted condition variable descriptor.

Side-effect: This routine calls the rescheduling procedure if one or more tasks are woken up as a result of the operation.

Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

int rt_cond_create RT_COND *  cond,
const char *  name
 

Create a condition variable.

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

Parameters:
cond The address of a condition variable descriptor RTAI will use to store the variable-related data. This descriptor must always be valid while the variable is active therefore it must be allocated in permanent memory.
name An ASCII string standing for the symbolic name of the condition variable. 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 variable.
Returns:
0 is returned upon success. Otherwise:
  • -EEXIST is returned if the name is already in use by some registered object.

Context: This routine can be called on behalf of a task or from the initialization code.

int rt_cond_delete RT_COND *  cond  ) 
 

Delete a condition variable.

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

Parameters:
cond The descriptor address of the affected condition variable.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if cond is not a condition variable descriptor.

  • -EIDRM is returned if cond is a deleted condition variable descriptor.

Side-effect: This routine calls the rescheduling procedure if tasks have been woken up as a result of the deletion.

Context: This routine can always be called on behalf of a task, or from the initialization code.

int rt_cond_inquire RT_COND *  cond,
RT_COND_INFO *  info
 

Inquire about a condition variable.

Return various information about the status of a given condition variable.

Parameters:
cond The descriptor address of the inquired condition variable.
info The address of a structure the condition variable 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 cond is not a condition variable descriptor.

  • -EIDRM is returned if cond is a deleted condition variable descriptor.

Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

int rt_cond_signal RT_COND *  cond  ) 
 

Signal a condition variable.

If the condition variable is pended, the first waiting task (by queuing priority order) is immediately unblocked.

Parameters:
cond The descriptor address of the affected condition variable.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if cond is not a condition variable descriptor.

  • -EIDRM is returned if cond is a deleted condition variable descriptor.

Side-effect: This routine calls the rescheduling procedure if a task is woken up as a result of the operation.

Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

int rt_cond_wait RT_COND *  cond,
RT_MUTEX *  mutex,
RTIME  timeout
 

Wait on a condition.

This service atomically release the mutex and causes the calling task to block on the specified condition variable. The caller will be unblocked when the variable is signaled, and the mutex re-acquired before returning from this service.

Tasks pend on condition variables by priority order.

Parameters:
cond The descriptor address of the affected condition variable.
mutex The descriptor address of the mutex protecting the condition variable.
timeout The number of clock ticks to wait for the condition variable to be signaled (see note). Passing RT_TIME_INFINITE causes the caller to block indefinitely until the condition variable is signaled.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if mutex is not a mutex descriptor, or cond is not a condition variable descriptor.

  • -EIDRM is returned if mutex or cond is a deleted object descriptor, including if the deletion occurred while the caller was sleeping on the variable.

  • -EINTR is returned if rt_task_unblock() has been called for the waiting task before the condition variable has been signaled.

  • -EWOULDBLOCK is returned if timeout equals RT_TIME_NONBLOCK.

Side-effect: This routine always calls the rescheduling procedure.

Context: This routine must be called on behalf of a task.

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 expressed as periodic jiffies. In oneshot mode, clock ticks are expressed in nanoseconds.


Generated on Mon Aug 30 13:58:39 2004 for RTAI API by doxygen 1.3.8