Condition Variable

Data Structures
struct	CondVar

Macros
#define	cvarInit(cv, ...)   _cvarInit(cv, opt_flags(__VA_ARGS__))

Typedefs
typedef struct CondVar	CondVar

Enumerations
enum	CONDVAR_Flags { CONDVAR_NoSpin = 1 }
	Condition variable initialization flags. More...

Functions
void	cvarDestroy (CondVar *cv)
_Requires_lock_held_ m bool	cvarWaitTimeout (CondVar *cv, Mutex *m, int64 timeout)
_Requires_lock_held_ m bool	cvarWait (CondVar *cv, Mutex *m)
bool	cvarSignal (CondVar *cv)
bool	cvarBroadcast (CondVar *cv)

Detailed Description

A condition variable lets a thread sleep until another thread signals that some shared state has changed, without racing to miss a signal that arrives between checking the state and going to sleep.

CondVar is always used together with a Mutex that guards the condition being waited on. Call cvarWait() or cvarWaitTimeout() with that mutex already held: the wait atomically releases the mutex while sleeping, then re-acquires it before returning if it was signaled. If the wait times out instead, the mutex is left unlocked rather than being re-acquired.

Because a signal can arrive just before a wait begins, or a thread can be woken without the condition actually being true yet, always re-check the condition in a loop rather than assuming a single cvarWait() call means the condition holds.

Basic usage:

Mutex m;
CondVar cv;
mutexInit(&m);
cvarInit(&cv);
 
// Thread 1: wait for the condition
mutexAcquire(&m);
while (!conditionIsTrue)
    cvarWait(&cv, &m);
mutexRelease(&m);
 
// Thread 2: change the condition and wake a waiter
mutexAcquire(&m);
conditionIsTrue = true;
mutexRelease(&m);
cvarSignal(&cv);
 
cvarDestroy(&cv);
mutexDestroy(&m);

For simple signaling that doesn't need a mutex-guarded predicate, an Event is usually a better fit. Reach for CondVar specifically when you want the classic "wait until this condition, checked under a lock, becomes true" pattern.

Note

This header is not included by the <cx/thread.h> aggregate header. Include <cx/thread/condvar.h> directly to use CondVar.

Macro Definition Documentation

cvarInit

#define cvarInit	(		cv,
			...
	)		_cvarInit(cv, opt_flags(__VA_ARGS__))

void cvarInit(CondVar *cv, [flags])

Initialize a condition variable for use.

Must be called before using any other condition variable operations.

Parameters

cv	Pointer to uninitialized condition variable structure
...	(flags) Optional CONDVAR_Flags (e.g., CONDVAR_NoSpin)

Definition at line 84 of file condvar.h.

Typedef Documentation

CondVar

typedef struct CondVar CondVar

Condition variable synchronization primitive

Used together with a Mutex to let threads wait for a shared condition to become true.

Enumeration Type Documentation

CONDVAR_Flags

enum CONDVAR_Flags

Condition variable initialization flags.

Enumerator
CONDVAR_NoSpin	Disable adaptive spinning, use kernel futex immediately.

Definition at line 61 of file condvar.h.

Function Documentation

cvarBroadcast()

bool cvarBroadcast

(

CondVar *

cv

)

Wake all threads waiting on a condition variable

If no threads are currently waiting, the broadcast has no lasting effect. It is not remembered for a future wait.

Parameters

cv	Condition variable to broadcast to

Returns

true on success

cvarDestroy()

void cvarDestroy

(

CondVar *

cv

)

Destroy a condition variable and release its resources

Cleans up the condition variable after use. There must be no threads waiting on it when destroyed. After destruction, the condition variable must be reinitialized before it can be used again.

Parameters

cv	Condition variable to destroy

cvarSignal()

bool cvarSignal

(

CondVar *

cv

)

Wake one thread waiting on a condition variable

If no thread is currently waiting, the signal has no lasting effect. It is not remembered for a future wait.

Parameters

cv	Condition variable to signal

Returns

true on success

cvarWait()

_Requires_lock_held_ m bool cvarWait ( CondVar *  cv, Mutex *  m  )

inline

Wait on a condition variable indefinitely

Must be called with m already held. Atomically releases m and blocks the calling thread until another thread calls cvarSignal() or cvarBroadcast() on cv, then re-acquires m before returning. Equivalent to cvarWaitTimeout() with timeForever.

Parameters

cv	Condition variable to wait on
m	Mutex currently held, guarding the condition

Definition at line 116 of file condvar.h.

References cvarWaitTimeout(), and timeForever.

cvarWaitTimeout()

_Requires_lock_held_ m bool cvarWaitTimeout	(	CondVar *	cv,
		Mutex *	m,
		int64	timeout
	)

Wait on a condition variable with a timeout

Must be called with m already held. Atomically releases m and blocks the calling thread until another thread calls cvarSignal() or cvarBroadcast() on cv, or the timeout elapses.

If the wait is signaled, m is re-acquired before this function returns. If the wait times out, m is left unlocked.

Parameters

cv	Condition variable to wait on
m	Mutex currently held, guarding the condition
timeout	Maximum time to wait in nanoseconds (use timeForever for infinite)

Returns

true if signaled and m was re-acquired; false if the timeout elapsed and m was left unlocked

Referenced by cvarWait().