Condition Variables
[Synchronization]

Collaboration diagram for Condition Variables:

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 CondVars together can implement a Monitor construct.
In order to use the Condition Variables APIs the CH_USE_CONDVARS option must be enabled in chconf.h.

Data Structures
struct	CondVar
	CondVar structure. More...
Defines
#define	_CONDVAR_DATA(name) {_THREADSQUEUE_DATA(name.c_queue)}
	Data part of a static condition variable initializer.
#define	CONDVAR_DECL(name) CondVar name = _CONDVAR_DATA(name)
	Static condition variable initializer.
Typedefs
typedef struct CondVar	CondVar
	CondVar structure.
Functions
void	chCondInit (CondVar *cp)
	Initializes s `CondVar` structure.
void	chCondSignal (CondVar *cp)
	Signals one thread that is waiting on the condition variable.
void	chCondSignalI (CondVar *cp)
	Signals one thread that is waiting on the condition variable.
void	chCondBroadcast (CondVar *cp)
	Signals all threads that are waiting on the condition variable.
void	chCondBroadcastI (CondVar *cp)
	Signals all threads that are waiting on the condition variable.
msg_t	chCondWait (CondVar *cp)
	Waits on the condition variable releasing the mutex lock.
msg_t	chCondWaitS (CondVar *cp)
	Waits on the condition variable releasing the mutex lock.
msg_t	chCondWaitTimeout (CondVar *cp, systime_t time)
	Waits on the condition variable releasing the mutex lock.
msg_t	chCondWaitTimeoutS (CondVar *cp, systime_t time)
	Waits on the condition variable releasing the mutex lock.

Define Documentation

#define _CONDVAR_DATA ( name ) {_THREADSQUEUE_DATA(name.c_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] name the name of the condition variable

Definition at line 83 of file chcond.h.

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

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 92 of file chcond.h.

Typedef Documentation

typedef struct CondVar CondVar

CondVar structure.

Function Documentation

void chCondInit ( CondVar * cp )

Initializes s CondVar structure.

Note:: This function can be invoked from within an interrupt handler even if it is not an I-Class API because it does not touch any critical kernel data structure.

Parameters:

[out] cp pointer to a CondVar structure

Definition at line 59 of file chcond.c.

References CondVar::c_queue, chDbgCheck, and queue_init.

Referenced by chibios_rt::CondVar::CondVar().

void chCondSignal ( CondVar * cp )

Signals one thread that is waiting on the condition variable.

Parameters:

[in] cp pointer to the CondVar structure

Definition at line 71 of file chcond.c.

References CondVar::c_queue, chDbgCheck, chSchWakeupS(), chSysLock, chSysUnlock, fifo_remove(), notempty, and RDY_OK.

Referenced by chibios_rt::CondVar::Signal().

Here is the call graph for this function:

void chCondSignalI ( CondVar * cp )

Signals one thread that is waiting on the condition variable.

Parameters:

[in] cp pointer to the CondVar structure

Definition at line 86 of file chcond.c.

References CondVar::c_queue, chDbgCheck, chSchReadyI(), fifo_remove(), notempty, Thread::p_u, RDY_OK, and Thread::rdymsg.

Here is the call graph for this function:

void chCondBroadcast ( CondVar * cp )

Signals all threads that are waiting on the condition variable.

Parameters:

[in] cp pointer to the CondVar structure

Definition at line 99 of file chcond.c.

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

Referenced by chibios_rt::CondVar::Broadcast().

Here is the call graph for this function:

void chCondBroadcastI ( CondVar * cp )

Signals all threads that are waiting on the condition variable.

Parameters:

[in] cp pointer to the CondVar structure

Definition at line 112 of file chcond.c.

References CondVar::c_queue, chDbgCheck, chSchReadyI(), fifo_remove(), ThreadsQueue::p_next, Thread::p_u, RDY_RESET, and Thread::rdymsg.

Referenced by chCondBroadcast().

Here is the call graph for this function:

msg_t chCondWait ( CondVar * 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.

Note:: The invoking thread must have at least one owned mutex on entry.

Parameters:

[in] cp pointer to the CondVar structure

Returns:: The wakep mode.

Return values:

	RDY_OK	if the condvar was signaled using `chCondSignal()`.
	RDY_RESET	if the condvar was signaled using `chCondBroadcast()`.

Definition at line 136 of file chcond.c.

References chCondWaitS(), chSysLock, and chSysUnlock.

Referenced by chibios_rt::CondVar::Wait().

Here is the call graph for this function:

msg_t chCondWaitS ( CondVar * 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.

Note:: The invoking thread must have at least one owned mutex on entry.

Parameters:

[in] cp pointer to the CondVar structure

Returns:: The wakep mode.

Return values:

	RDY_OK	if the condvar was signaled using `chCondSignal()`.
	RDY_RESET	if the condvar was signaled using `chCondBroadcast()`.

Definition at line 158 of file chcond.c.

References CondVar::c_queue, chDbgAssert, chDbgCheck, chMtxLockS(), chMtxUnlockS(), chSchGoSleepS(), currp, Thread::p_mtxlist, Thread::p_u, prio_insert(), Thread::rdymsg, THD_STATE_WTCOND, and Thread::wtobjp.

Referenced by chCondWait().

Here is the call graph for this function:

msg_t chCondWaitTimeout	(	CondVar *	cp,
		systime_t	time
	)

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.

Note:: The invoking thread must have at least one owned mutex on entry.; Exiting the function because a timeout does not re-acquire the mutex, the mutex ownership is lost.

Parameters:

`[in]`	cp	pointer to the `CondVar` structure
`[in]`	time	the number of ticks before the operation timeouts, the special value `TIME_INFINITE` is allowed. It is not possible to specify zero `TIME_IMMEDIATE` as timeout specification because it would make no sense in this function.

Returns:: The wakep mode.

Return values:

	RDY_OK	if the condvar was signaled using `chCondSignal()`.
	RDY_RESET	if the condvar was signaled using `chCondBroadcast()`.
	RDY_TIMEOUT	if the condvar was not signaled `within` the specified timeout.

Definition at line 200 of file chcond.c.

References chCondWaitTimeoutS(), chSysLock, and chSysUnlock.

Referenced by chibios_rt::CondVar::WaitTimeout().

Here is the call graph for this function:

msg_t chCondWaitTimeoutS	(	CondVar *	cp,
		systime_t	time
	)

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.

Note:: The invoking thread must have at least one owned mutex on entry.; Exiting the function because a timeout does not re-acquire the mutex, the mutex ownership is lost.

Parameters:

`[in]`	cp	pointer to the `CondVar` structure
`[in]`	time	the number of ticks before the operation timeouts, the special value `TIME_INFINITE` is allowed. It is not possible to specify zero `TIME_IMMEDIATE` as timeout specification because it would make no sense in this function.

Returns:: The wakep mode.

Return values:

	RDY_OK	if the condvar was signaled using `chCondSignal()`.
	RDY_RESET	if the condvar was signaled using `chCondBroadcast()`.
	RDY_TIMEOUT	if the condvar was not signaled within the specified timeout.

Definition at line 231 of file chcond.c.

References CondVar::c_queue, chDbgAssert, chDbgCheck, chMtxLockS(), chMtxUnlockS(), chSchGoSleepTimeoutS(), currp, prio_insert(), RDY_TIMEOUT, and THD_STATE_WTCOND.

Referenced by chCondWaitTimeout().

Here is the call graph for this function:

Condition Variables [Synchronization]

Description

Operation mode

Data Structures

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation

Condition Variables
[Synchronization]