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.

Collaboration diagram for Condition Variables:

Data Structures
struct	condition_variable
	condition_variable_t structure. More...

Macros
#define	__CONDVAR_DATA(name)
	Data part of a static condition variable initializer.
#define	CONDVAR_DECL(name)
	Static condition variable initializer.

Typedefs
typedef struct condition_variable	condition_variable_t
	condition_variable_t structure.

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

Macro Definition Documentation

◆ __CONDVAR_DATA

#define __CONDVAR_DATA ( name )

Value:

{__CH_QUEUE_DATA(name.queue)}

__CH_QUEUE_DATA

#define __CH_QUEUE_DATA(name)

Data part of a static queue object initializer.

Definition chlists.h:117

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] name the name of the condition variable

Definition at line 75 of file chcond.h.

◆ CONDVAR_DECL

#define CONDVAR_DECL ( name )

Value:

condition_variable_t name = __CONDVAR_DATA(name)

condition_variable_t

struct condition_variable condition_variable_t

condition_variable_t structure.

__CONDVAR_DATA

#define __CONDVAR_DATA(name)

Data part of a static condition variable initializer.

Definition chcond.h:75

Static condition variable initializer.

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

Parameters

[in] name the name of the condition variable

Definition at line 84 of file chcond.h.

Typedef Documentation

◆ condition_variable_t

typedef struct condition_variable condition_variable_t

condition_variable_t structure.

Function Documentation

◆ chCondObjectInit()

void chCondObjectInit ( condition_variable_t * cp )

Initializes s condition_variable_t structure.

Parameters

[out] cp pointer to a condition_variable_t structure

Function Class:: Object or module nitializer function.

Definition at line 75 of file chcond.c.

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

Here is the call graph for this function:

◆ chCondSignal()

void chCondSignal ( condition_variable_t * cp )

Signals one thread that is waiting on the condition variable.

Parameters

[in] cp pointer 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 ch_queue_fifo_remove(), ch_queue_notempty(), chDbgCheck, chSchWakeupS, chSysLock, chSysUnlock, MSG_OK, condition_variable::queue, and threadref.

Here is the call graph for this function:

◆ chCondSignalI()

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] cp pointer 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 ch_queue_fifo_remove(), ch_queue_notempty(), chDbgCheck, chDbgCheckClassI, chSchReadyI(), MSG_OK, condition_variable::queue, ch_thread::rdymsg, threadref, and ch_thread::u.

Here is the call graph for this function:

◆ chCondBroadcast()

void chCondBroadcast ( condition_variable_t * cp )

Signals all threads that are waiting on the condition variable.

Parameters

[in] cp pointer 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:

◆ chCondBroadcastI()

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] cp pointer 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 ch_queue_fifo_remove(), ch_queue_notempty(), chDbgCheck, chDbgCheckClassI, chSchReadyI(), MSG_RESET, condition_variable::queue, ch_thread::rdymsg, threadref, and ch_thread::u.

Referenced by chCondBroadcast().

Here is the call graph for this function:

◆ chCondWait()

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] cp pointer to the condition_variable_t structure

Returns: A message specifying how the invoking thread has been released from the condition variable.

Return values

MSG_OK	if the condition variable has been signaled using `chCondSignal()`.
MSG_RESET	if 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:

◆ chCondWaitS()

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] cp pointer to the condition_variable_t structure

Returns: A message specifying how the invoking thread has been released from the condition variable.

Return values

MSG_OK	if the condition variable has been signaled using `chCondSignal()`.
MSG_RESET	if 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_sch_prio_insert(), CH_STATE_WTCOND, chDbgAssert, chDbgCheck, chDbgCheckClassS, chMtxGetNextMutexX(), chMtxLockS(), chMtxUnlockS(), chSchGoSleepS, chThdGetSelfX, ch_thread::hdr, ch_thread::queue, condition_variable::queue, ch_thread::rdymsg, ch_thread::u, and ch_thread::wtobjp.

Referenced by chCondWait().

Here is the call graph for this function:

◆ chCondWaitTimeout()

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]	cp	pointer to the `condition_variable_t` structure
[in]	timeout	the 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_OK	if the condition variable has been signaled using `chCondSignal()`.
MSG_RESET	if the condition variable has been signaled using `chCondBroadcast()`.
MSG_TIMEOUT	if 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 257 of file chcond.c.

References chCondWaitTimeoutS(), chSysLock, and chSysUnlock.

Here is the call graph for this function:

◆ chCondWaitTimeoutS()

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]	cp	pointer to the `condition_variable_t` structure
[in]	timeout	the 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_OK	if the condition variable has been signaled using `chCondSignal()`.
MSG_RESET	if the condition variable has been signaled using `chCondBroadcast()`.
MSG_TIMEOUT	if 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 295 of file chcond.c.

References ch_sch_prio_insert(), CH_STATE_WTCOND, chDbgAssert, chDbgCheck, chDbgCheckClassS, chMtxGetNextMutexX(), chMtxLockS(), chMtxUnlockS(), chSchGoSleepTimeoutS(), chThdGetSelfX, ch_thread::hdr, MSG_TIMEOUT, ch_thread::queue, condition_variable::queue, TIME_IMMEDIATE, ch_thread::u, and ch_thread::wtobjp.

Referenced by chCondWaitTimeout().

Here is the call graph for this function:

Detailed Description

Operation mode

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ __CONDVAR_DATA

◆ CONDVAR_DECL

Typedef Documentation

◆ condition_variable_t

Function Documentation

◆ chCondObjectInit()

◆ chCondSignal()

◆ chCondSignalI()

◆ chCondBroadcast()

◆ chCondBroadcastI()

◆ chCondWait()

◆ chCondWaitS()

◆ chCondWaitTimeout()

◆ chCondWaitTimeoutS()