XII Release 0.1.0
Loading...
Searching...
No Matches
Public Types | Public Member Functions | List of all members
xiiConditionVariable Class Reference

Condition variables are used to put threads to sleep and wake them up upon certain events. More...

#include <ConditionVariable.h>

Public Types

enum class  WaitResult { Signaled , Timeout }
 

Public Member Functions

void Lock ()
 Locks the internal mutex. Recursive locking is allowed.
 
xiiResult TryLock ()
 Tries to lock the internal mutex. Recursive locking is allowed.
 
void Unlock ()
 Unlocks the internal mutex. Must be called as often as it was locked.
 
void SignalOne ()
 Wakes up one of the threads that are currently waiting for the variable.
 
void SignalAll ()
 Wakes up all the threads that are currently waiting for the variable.
 
void UnlockWaitForSignalAndLock () const
 Puts the calling thread to sleep and waits for the variable to get signaled.
 
WaitResult UnlockWaitForSignalAndLock (xiiTime timeout) const
 Same as UnlockWaitForSignalAndLock() but with an additional timeout condition.
 

Detailed Description

Condition variables are used to put threads to sleep and wake them up upon certain events.

The xiiConditionVariable works in conjunction with a mutex. When waiting for a signal, the OS typically puts the waiting thread to sleep. Using SignalOne() or SignalAll() other threads can wake up one or all threads that are currently waiting on the condition variable.

When a thread is woken up, it automatically holds the lock on the condition variable's mutex, which can be used to safely access or modify certain state.

xiiConditionVariable is a low-level threading construct. Higher level functionality such as xiiThreadSignal may be more suitable for most use cases.

See also
xiiThreadSignal

Member Function Documentation

◆ SignalAll()

void xiiConditionVariable::SignalAll ( )

Wakes up all the threads that are currently waiting for the variable.

If no thread is currently waiting, this has no effect.

◆ SignalOne()

void xiiConditionVariable::SignalOne ( )

Wakes up one of the threads that are currently waiting for the variable.

If no thread is currently waiting, this has no effect. In rare cases more than one thread can be woken up, called a spurious wake up.

◆ UnlockWaitForSignalAndLock() [1/2]

void xiiConditionVariable::UnlockWaitForSignalAndLock ( ) const

Puts the calling thread to sleep and waits for the variable to get signaled.

Asserts that the xiiConditionVariable is locked when the function is called. The mutex will be unlocked and the thread is put to sleep. When the signal arrives, the thread is woken up and the mutex is locked again.

◆ UnlockWaitForSignalAndLock() [2/2]

xiiConditionVariable::WaitResult xiiConditionVariable::UnlockWaitForSignalAndLock ( xiiTime timeout) const

Same as UnlockWaitForSignalAndLock() but with an additional timeout condition.

If the timeout is reached before the signal arrived, the function returns with WaitResult::Timeout.

Note
If the timeout is reached, the mutex will still get locked!
The documentation for this class was generated from the following files: