ChibiOS/RT  5.1.0
Condition Variables
Collaboration diagram for Condition Variables:

Detailed Description

This module implements the Condition Variables mechanism. Condition variables are an extensions to the mutex subsystem and cannot work alone.

Operation mode

The condition variable is a synchronization object meant to be used inside a zone protected by a mutex. Mutexes and condition variables together can implement a Monitor construct.

Precondition
In order to use the condition variable APIs the CH_CFG_USE_CONDVARS option must be enabled in chconf.h.

Macros

#define _CONDVAR_DATA(name)   {_THREADS_QUEUE_DATA(name.queue)}
 Data part of a static condition variable initializer. More...
 
#define CONDVAR_DECL(name)   condition_variable_t name = _CONDVAR_DATA(name)
 Static condition variable initializer. More...
 

Typedefs

typedef struct condition_variable condition_variable_t
 condition_variable_t structure. More...
 

Data Structures

struct  condition_variable
 condition_variable_t structure. More...
 

Functions

void chCondObjectInit (condition_variable_t *cp)
 Initializes s condition_variable_t structure. More...
 
void chCondSignal (condition_variable_t *cp)
 Signals one thread that is waiting on the condition variable. More...
 
void chCondSignalI (condition_variable_t *cp)
 Signals one thread that is waiting on the condition variable. More...
 
void chCondBroadcast (condition_variable_t *cp)
 Signals all threads that are waiting on the condition variable. More...
 
void chCondBroadcastI (condition_variable_t *cp)
 Signals all threads that are waiting on the condition variable. More...
 
msg_t chCondWait (condition_variable_t *cp)
 Waits on the condition variable releasing the mutex lock. More...
 
msg_t chCondWaitS (condition_variable_t *cp)
 Waits on the condition variable releasing the mutex lock. More...
 
msg_t chCondWaitTimeout (condition_variable_t *cp, sysinterval_t timeout)
 Waits on the condition variable releasing the mutex lock. More...
 
msg_t chCondWaitTimeoutS (condition_variable_t *cp, sysinterval_t timeout)
 Waits on the condition variable releasing the mutex lock. More...
 

Macro Definition Documentation

#define _CONDVAR_DATA (   name)    {_THREADS_QUEUE_DATA(name.queue)}

Data part of a static condition variable initializer.

This macro should be used when statically initializing a condition variable that is part of a bigger structure.

Parameters
[in]namethe name of the condition variable

Definition at line 75 of file chcond.h.

#define CONDVAR_DECL (   name)    condition_variable_t name = _CONDVAR_DATA(name)

Static condition variable initializer.

Statically initialized condition variables require no explicit initialization using chCondInit().

Parameters
[in]namethe name of the condition variable

Definition at line 84 of file chcond.h.

Typedef Documentation

condition_variable_t structure.

Function Documentation

void chCondObjectInit ( condition_variable_t cp)

Initializes s condition_variable_t structure.

Parameters
[out]cppointer to a condition_variable_t structure
Function Class:
Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 75 of file chcond.c.

References chDbgCheck, condition_variable::queue, and queue_init().

Here is the call graph for this function:

void chCondSignal ( condition_variable_t cp)

Signals one thread that is waiting on the condition variable.

Parameters
[in]cppointer to the condition_variable_t structure
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 89 of file chcond.c.

References chDbgCheck, chSchWakeupS(), chSysLock(), chSysUnlock(), MSG_OK, condition_variable::queue, queue_fifo_remove(), and queue_notempty().

Here is the call graph for this function:

void chCondSignalI ( condition_variable_t cp)

Signals one thread that is waiting on the condition variable.

Postcondition
This function does not reschedule so a call to a rescheduling function must be performed before unlocking the kernel. Note that interrupt handlers always reschedule on exit so an explicit reschedule must not be performed in ISRs.
Parameters
[in]cppointer to the condition_variable_t structure
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 111 of file chcond.c.

References chDbgCheck, chDbgCheckClassI(), chSchReadyI(), MSG_OK, condition_variable::queue, queue_fifo_remove(), queue_notempty(), ch_thread::rdymsg, and ch_thread::u.

Here is the call graph for this function:

void chCondBroadcast ( condition_variable_t cp)

Signals all threads that are waiting on the condition variable.

Parameters
[in]cppointer to the condition_variable_t structure
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 130 of file chcond.c.

References chCondBroadcastI(), chSchRescheduleS(), chSysLock(), and chSysUnlock().

Here is the call graph for this function:

void chCondBroadcastI ( condition_variable_t cp)

Signals all threads that are waiting on the condition variable.

Postcondition
This function does not reschedule so a call to a rescheduling function must be performed before unlocking the kernel. Note that interrupt handlers always reschedule on exit so an explicit reschedule must not be performed in ISRs.
Parameters
[in]cppointer to the condition_variable_t structure
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 149 of file chcond.c.

References chDbgCheck, chDbgCheckClassI(), chSchReadyI(), MSG_RESET, condition_variable::queue, queue_fifo_remove(), queue_notempty(), ch_thread::rdymsg, and ch_thread::u.

Referenced by chCondBroadcast().

Here is the call graph for this function:

msg_t chCondWait ( condition_variable_t cp)

Waits on the condition variable releasing the mutex lock.

Releases the currently owned mutex, waits on the condition variable, and finally acquires the mutex again. All the sequence is performed atomically.

Precondition
The invoking thread must have at least one owned mutex.
Parameters
[in]cppointer to the condition_variable_t structure
Returns
A message specifying how the invoking thread has been released from the condition variable.
Return values
MSG_OKif the condition variable has been signaled using chCondSignal().
MSG_RESETif the condition variable has been signaled using chCondBroadcast().
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 179 of file chcond.c.

References chCondWaitS(), chSysLock(), and chSysUnlock().

Here is the call graph for this function:

msg_t chCondWaitS ( condition_variable_t cp)

Waits on the condition variable releasing the mutex lock.

Releases the currently owned mutex, waits on the condition variable, and finally acquires the mutex again. All the sequence is performed atomically.

Precondition
The invoking thread must have at least one owned mutex.
Parameters
[in]cppointer to the condition_variable_t structure
Returns
A message specifying how the invoking thread has been released from the condition variable.
Return values
MSG_OKif the condition variable has been signaled using chCondSignal().
MSG_RESETif the condition variable has been signaled using chCondBroadcast().
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 205 of file chcond.c.

References CH_STATE_WTCOND, chDbgAssert, chDbgCheck, chDbgCheckClassS(), chMtxGetNextMutexS(), chMtxLockS(), chMtxUnlockS(), chSchGoSleepS(), currp, ch_thread::mtxlist, condition_variable::queue, queue_prio_insert(), ch_thread::rdymsg, ch_thread::u, and ch_thread::wtobjp.

Referenced by chCondWait().

Here is the call graph for this function:

msg_t chCondWaitTimeout ( condition_variable_t cp,
sysinterval_t  timeout 
)

Waits on the condition variable releasing the mutex lock.

Releases the currently owned mutex, waits on the condition variable, and finally acquires the mutex again. All the sequence is performed atomically.

Precondition
The invoking thread must have at least one owned mutex.
The configuration option CH_CFG_USE_CONDVARS_TIMEOUT must be enabled in order to use this function.
Postcondition
Exiting the function because a timeout does not re-acquire the mutex, the mutex ownership is lost.
Parameters
[in]cppointer to the condition_variable_t structure
[in]timeoutthe number of ticks before the operation timeouts, the special values are handled as follow:
  • TIME_INFINITE no timeout.
  • TIME_IMMEDIATE this value is not allowed.
Returns
A message specifying how the invoking thread has been released from the condition variable.
Return values
MSG_OKif the condition variable has been signaled using chCondSignal().
MSG_RESETif the condition variable has been signaled using chCondBroadcast().
MSG_TIMEOUTif the condition variable has not been signaled within the specified timeout.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 258 of file chcond.c.

References chCondWaitTimeoutS(), chSysLock(), and chSysUnlock().

Here is the call graph for this function:

msg_t chCondWaitTimeoutS ( condition_variable_t cp,
sysinterval_t  timeout 
)

Waits on the condition variable releasing the mutex lock.

Releases the currently owned mutex, waits on the condition variable, and finally acquires the mutex again. All the sequence is performed atomically.

Precondition
The invoking thread must have at least one owned mutex.
The configuration option CH_CFG_USE_CONDVARS_TIMEOUT must be enabled in order to use this function.
Postcondition
Exiting the function because a timeout does not re-acquire the mutex, the mutex ownership is lost.
Parameters
[in]cppointer to the condition_variable_t structure
[in]timeoutthe number of ticks before the operation timeouts, the special values are handled as follow:
  • TIME_INFINITE no timeout.
  • TIME_IMMEDIATE this value is not allowed.
Returns
A message specifying how the invoking thread has been released from the condition variable.
Return values
MSG_OKif the condition variable has been signaled using chCondSignal().
MSG_RESETif the condition variable has been signaled using chCondBroadcast().
MSG_TIMEOUTif the condition variable has not been signaled within the specified timeout.
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 296 of file chcond.c.

References CH_STATE_WTCOND, chDbgAssert, chDbgCheck, chDbgCheckClassS(), chMtxGetNextMutexS(), chMtxLockS(), chMtxUnlockS(), chSchGoSleepTimeoutS(), currp, MSG_TIMEOUT, condition_variable::queue, queue_prio_insert(), and TIME_IMMEDIATE.

Referenced by chCondWaitTimeout().

Here is the call graph for this function: