Condition-Variables

Table of Contents

• Overview
• Initialize a Condition-Variable
• Waiting on a Condition-Variable
• Waiting on multiple Condition-Variables?
• Send a Signal to a Condition-Variable to one waiting Thread
• Send a Condition-Variable Broadcast to all waiting Threads

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.

fplConditionVariable condition;
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);
}
fplMutexUnlock(&mutex);

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
fplConditionSignal(&cond);

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(&cond);