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 handle 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.

See Synchronization methods for a comparison with the other synchronization primitives.

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.

 condition;
if (!(&condition)) {
    // Error: Condition-Variable failed to initialize -> This will most likely never happen
}

// ... Condition-Variable is not required anymore
(&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 occur.

(&mutex);
{
    // Wait until the Condition-Variable is signaled or broadcasted
    (&condition, &mutex, );

    // ... or

    // Wait at max for 5 seconds for a signal or broadcast on the Condition-Variable
    (&condition, &mutex, 5000);
}
(&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 do not need a Mutex for signaling.

// Send a Signal to the Condition-Variable to one waiting Thread
(&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 do not need a Mutex for signaling a Condition-Variable.

// Broadcast a Signal to the Condition-Variable to all waiting Threads
(&cond);