Final Platform Layer  0.9.6-beta
Condition-Variables

Overview

This section explains how to create and handling of Condition-Variables.
A Condition-Variable is a User-Level Object used to let Threads wait until a Condition-Variable is signaled or broadcasted.
Unlike Signals, Condition-Variables requires you to use a fplMutexHandle as a locking mechanism.
They cannot be shared across process boundaries but the number of Condition-Variables is only limited by the amount of memory you have.

Initialize a Condition-Variable

Call fplConditionInit() with a pointer to fplConditionVariable as an argument, to initialize a Condition-Variable.
When you are done with that Condition-Variable, you need to call fplConditionDestroy() to release its internal resources.

if (!fplConditionInit(&condition)) {
// Error: Condition-Variable failed to initialize -> This will most likely never happen
}
// ... Condition-Variable is not required anymore
fplConditionDestroy(&condition);

Waiting on a Condition-Variable

Call fplConditionWait() with a pointer to fplConditionVariable and a pointer to fplMutexHandle as an argument, to let a thread wait on that Condition-Variable.
Also, you need to specify the number of milliseconds you want the Thread to wait. If FPL_TIMEOUT_INFINITE is passed, it will wait forever.

Note
Conditions must be called inside a locked critical-section or undefined behavior may happen.
fplMutexLock(&mutex);
{
// Wait until the Condition-Variable is signaled or broadcasted
fplConditionWait(&condition, &mutex, FPL_TIMEOUT_INFINITE);
// ... or
// Wait at max for 5 seconds for a signal or broadcast on the Condition-Variable
fplConditionWait(&condition, &mutex, 5000);
}

Waiting on multiple Condition-Variables?

A Thread can only wait on one single Condition-Variable at a time - if you need to wait on multiple Condition-Variables, you should consider using Signals .

Send a Signal to a Condition-Variable to one waiting Thread

Call fplConditionSignal() with a pointer to fplConditionVariable, to signal any waiting Threads.
If you want to let multiple Threads waits on the same Condition-Variable, use fplConditionBroadcast() instead.

Note
Unlike Signals Condition-Variables does not need a Mutex for signaling.
// Send a Signal to the Condition-Variable to one waiting Thread

Send a Condition-Variable Broadcast to all waiting Threads

Call fplConditionBroadcast() with a pointer to fplConditionVariable, to signal all waiting Threads.
If you just need a single Thread to wait on the Condition-Variable, use fplConditionSignal() instead.

Note
Unlike Signals Condition-Variables does not need a Mutex for signaling a Condition-Variable.
// Broadcast a Signal to the Condition-Variable to all waiting Threads
fplConditionBroadcast
fpl_platform_api bool fplConditionBroadcast(fplConditionVariable *condition)
Wakes up all threads that wait on the given condition.
fplConditionVariable
The condition variable structure.
Definition: final_platform_layer.h:4593
FPL_TIMEOUT_INFINITE
#define FPL_TIMEOUT_INFINITE
Infinite timeout constant.
Definition: final_platform_layer.h:4412
fplMutexUnlock
fpl_platform_api bool fplMutexUnlock(fplMutexHandle *mutex)
Unlocks the given mutex.
fplConditionSignal
fpl_platform_api bool fplConditionSignal(fplConditionVariable *condition)
Wakes up one thread that waits on the given condition.
fplMutexLock
fpl_platform_api bool fplMutexLock(fplMutexHandle *mutex)
Locks the given mutex and blocks any other threads.
fplConditionInit
fpl_platform_api bool fplConditionInit(fplConditionVariable *condition)
Initialize s the given condition.
fplConditionWait
fpl_platform_api bool fplConditionWait(fplConditionVariable *condition, fplMutexHandle *mutex, const fplTimeoutValue timeout)
Sleeps on the given condition and releases the mutex when done.
fplConditionDestroy
fpl_platform_api void fplConditionDestroy(fplConditionVariable *condition)
Releases the given condition and clears the structure to zero.