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 wait on that Signal will wake up.

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.

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

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.

 mutex;
// Initialize a Signal as "unset"
if (!(&mutex, )) {
    // Error: Signal failed initializing -> Too many active Signals
}

// ... Signal is not required anymore
(&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
(thread, );

// ... or

// Wait at max for 5 seconds or until the Signal is set
(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:

 **signals; // Signals array already initialized

// Wait until one of the Signal is set
(signals, numOfSignals, sizeof( *), );

// ... or

// Wait at max for 5 seconds or until one of the Signal is set
(signals, numOfSignals, sizeof( *), 5000);

Example, custom struct with stored signal handle:

typedef struct MyCustomStruct {
    int a;
    void *ptr;
     *signal;
    short b;
} MyCustomStruct;

MyCustomStruct *customSignals; // Struct array already initialized

 *firstPointerToSignal = &customSignals[0].signal;

// Wait until one of the Signal is set
(firstPointerToSignal, numOfSignals, sizeof(MyCustomStruct), );

// ... or

// Wait at max for 5 seconds or until one of the Signal is set
(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:

 **signals; // Signals array already initialized

// Wait until all of the Signals are set
(signals, numOfSignals, sizeof( *), );

// ... or

// Wait at max for 5 seconds or until all of the Signal are set
(signals, numOfSignals, sizeof( *), 5000);

Example, custom struct with stored signal handle:

typedef struct MyCustomStruct {
    int a;
    void *ptr;
     *signal;
    short b;
} MyCustomStruct;

MyCustomStruct *customSignals; // Struct array already initialized

 *firstPointerToSignal = &customSignals[0].signal;

// Wait until all of the Signals are set
(firstPointerToSignal, numOfSignals, sizeof(MyCustomStruct), );

// ... or

// Wait at max for 5 seconds or until all of the Signal are set
(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
(&mutex);
(signal);
(&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
(&mutex);
(signal);
(&mutex);