Signals

Table of Contents

• Overview
• Initialize a Signal
• Waiting for Signal
  • Wait for a single Signal to be set
  • Wait for any Signal to be set
  • Wait for all Signals to be set
• Setting a Signal
• Resetting a Signal

Overview

This section explains how to create and manage Signals.
A Signal is a Kernel-Level object used to notify one or multiple waiting Threads.
It internally contains a Value which is either fplSignalValue_Set or fplSignalValue_Unset.
When this value gets changed, all Threads which waits on that Signal will wakeup.
They can be shared across process boundaries and may be used as standalone locks to shared data, but the number of Signals is limited by the OS that can be allocated at a time.

Initialize a Signal

Call fplSignalInit() with a pointer to fplSignalHandle as an argument, to initialize a Signal.
Also, you need to specify if the Signal starts as fplSignalValue_Set or fplSignalValue_Unset as a second argument.
When you are done with that Signal, you need to call fplSignalDestroy() to release its internal resources.

fplSignalHandle mutex;
// Initialize a Signal as "unset"
if (!fplSignalInit(&mutex, fplSignalValue_Unset)) {
    // Error: Signal failed initializing -> Too many active Signals
}
 
// ... Signal is not required anymore
fplSignalDestroy(&mutex);

Waiting for Signal

Wait for a single Signal to be set

Call fplSignalWaitForOne() with a pointer to fplSignalHandle and a fplTimeoutValue argument, to let the current thread wait until the Signal is set.

// Wait until the Signal is set
fplSignalWaitForOne(thread, FPL_TIMEOUT_INFINITE);
 
// ... or
 
// Wait at max for 5 seconds or until the Signal is set
fplSignalWaitForOne(thread, 5000);

Wait for any Signal to be set

Call fplSignalWaitForAny() to let the current thread wait until at least one Signal is set.

Example, default signal handle array:

fplSignalHandle **signals; // Signals array already initialized
 
// Wait until one of the Signal is set
fplSignalWaitForAny(signals, numOfSignals, sizeof(fplSignalHandle *), FPL_TIMEOUT_INFINITE);
 
// ... or
 
// Wait at max for 5 seconds or until one of the Signal is set
fplSignalWaitForAny(signals, numOfSignals, sizeof(fplSignalHandle *), 5000);

Example, custom struct with stored signal handle:

typedef struct MyCustomStruct {
    int a;
    void *ptr;
    fplSignalHandle *signal;
    short b;
} MyCustomStruct;
 
MyCustomStruct *customSignals; // Struct array already initialized
 
fplSignalHandle *firstPointerToSignal = &customSignals[0].signal;
 
// Wait until one of the Signal is set
fplSignalWaitForAny(firstPointerToSignal, numOfSignals, sizeof(MyCustomStruct), FPL_TIMEOUT_INFINITE);
 
// ... or
 
// Wait at max for 5 seconds or until one of the Signal is set
fplSignalWaitForAny(firstPointerToSignal, numOfSignals, sizeof(MyCustomStruct), 5000);

Wait for all Signals to be set

Call fplSignalWaitForAll() to let the current thread wait until all Signals are set.

Example, default signal handle array:

fplSignalHandle **signals; // Signals array already initialized
 
// Wait until all of the Signals are set
fplSignalWaitForAll(signals, numOfSignals, sizeof(fplSignalHandle *), FPL_TIMEOUT_INFINITE);
 
// ... or
 
// Wait at max for 5 seconds or until all of the Signal are set
fplSignalWaitForAll(signals, numOfSignals, sizeof(fplSignalHandle *), 5000);

Example, custom struct with stored signal handle:

typedef struct MyCustomStruct {
    int a;
    void *ptr;
    fplSignalHandle *signal;
    short b;
} MyCustomStruct;
 
MyCustomStruct *customSignals; // Struct array already initialized
 
fplSignalHandle *firstPointerToSignal = &customSignals[0].signal;
 
// Wait until all of the Signals are set
fplSignalWaitForAll(firstPointerToSignal, numOfSignals, sizeof(MyCustomStruct), FPL_TIMEOUT_INFINITE);
 
// ... or
 
// Wait at max for 5 seconds or until all of the Signal are set
fplSignalWaitForAll(firstPointerToSignal, numOfSignals, sizeof(MyCustomStruct), 5000);

Setting a Signal

Call fplSignalSet() with a pointer to fplSignalHandle as an argument, to set a Signal and wakeup all waiting Threads.

Note

Unlike fplConditionVariable , setting a Signal is not Thread-Safe so you should ensure that only one thread at a time will set it!

// Use a mutex or another synchronization method to ensure that only one thread can set the Signal
fplMutexLock(&mutex);
fplSignalSet(signal);
fplMutexUnlock(&mutex);

Resetting a Signal

Call fplSignalReset() with a pointer to fplSignalHandle as an argument, to reset a Signal.

Note

Unlike fplConditionVariable , resetting a Signal is not Thread-Safe so you should ensure that only one thread at a time will set it!

// Use a mutex or another synchronization method to ensure that only one thread can reset the Signal
fplMutexLock(&mutex);
fplSignalReset(signal);
fplMutexUnlock(&mutex);