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 CondVars together can implement a Monitor construct.

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

Data Structures
struct	CondVar
	CondVar structure. More...
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.
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.

Function Documentation

void chCondInit ( CondVar * cp )

Initializes s CondVar structure.

Parameters:

[out] cp pointer to a CondVar structure

Function Class:: Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 52 of file chcond.c.

References CondVar::c_queue, chDbgCheck, and queue_init.

void chCondSignal ( CondVar * cp )

Signals one thread that is waiting on the condition variable.

Parameters:

[in] cp pointer to the CondVar structure

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 66 of file chcond.c.

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

Here is the call graph for this function:

void chCondSignalI ( CondVar * 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 CondVar 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 87 of file chcond.c.

References CondVar::c_queue, chDbgCheck, chDbgCheckClassI(), chSchReadyI(), fifo_remove(), notempty, 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

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 103 of file chcond.c.

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

Here is the call graph for this function:

void chCondBroadcastI ( CondVar * 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 CondVar 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 122 of file chcond.c.

References CondVar::c_queue, chDbgCheck, chDbgCheckClassI(), chSchReadyI(), fifo_remove(), ThreadsQueue::p_next, 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.

Precondition:: The invoking thread must have at least one owned mutex.

Parameters:

[in] cp pointer to the CondVar structure

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

Return values:

RDY_OK	if the condvar has been signaled using `chCondSignal()`.
RDY_RESET	if the condvar 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 151 of file chcond.c.

References chCondWaitS(), chSysLock, and chSysUnlock.

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.

Precondition:: The invoking thread must have at least one owned mutex.

Parameters:

[in] cp pointer to the CondVar structure

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

Return values:

RDY_OK	if the condvar has been signaled using `chCondSignal()`.
RDY_RESET	if the condvar 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 177 of file chcond.c.

References CondVar::c_queue, chDbgAssert, chDbgCheck, chDbgCheckClassS(), chMtxLockS(), chMtxUnlockS(), chSchGoSleepS(), currp, Thread::p_mtxlist, 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.

Precondition:: The invoking thread must have at least one owned mutex.; The configuration option CH_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 `CondVar` structure
[in]	time	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:

RDY_OK	if the condvar has been signaled using `chCondSignal()`.
RDY_RESET	if the condvar has been signaled using `chCondBroadcast()`.
RDY_TIMEOUT	if the condvar 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 226 of file chcond.c.

References chCondWaitTimeoutS(), chSysLock, and chSysUnlock.

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.

Precondition:: The invoking thread must have at least one owned mutex.; The configuration option CH_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 `CondVar` structure
[in]	time	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:

RDY_OK	if the condvar has been signaled using `chCondSignal()`.
RDY_RESET	if the condvar has been signaled using `chCondBroadcast()`.
RDY_TIMEOUT	if the condvar 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 263 of file chcond.c.

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

Referenced by chCondWaitTimeout().

Here is the call graph for this function:

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

Typedef Documentation

typedef struct CondVar CondVar

CondVar structure.

Detailed Description

Operation mode

Data Structures

Functions

Defines

Typedefs

Function Documentation

Define Documentation

Typedef Documentation