Threads

Table of Contents

• Overview
• Creating a Thread
• Destroying a Thread?
• Waiting/Joining for Threads to Exit
  • Wait for a single Thread to Exit
  • Wait for any Thread to Exit
  • Wait for all Threads to Exit
• Terminate a thread
• Query the Thread State
• Notes

Overview

In this section, you will learn the Basics about creating and handling of Threads. With Threads, you can run multiple pieces of code in parallel. Threads require the use of Synchronization methods to prevent race conditions.

Creating a Thread

Call fplThreadCreate() with a pointer to callback and a user pointer argument, to create and immediately run a Thread.

void MyThreadProc(const  *context, void *data) {
    // ... do something here
}
void RunMyThread() {
    int myData = 42;
     *thread = (MyThreadProc, &myData);
    (thread, );
}

Note: The internal Thread resources will be cleaned up automatically after your code has finished running.

Warning: When a Thread has finished running, you cannot use the same

fplThreadHandle anymore -> It may be reassigned to another Thread in the future.

Destroying a Thread?

You don't have to manually release the Thread resources, this will be cleaned up automatically when either the Thread ends naturally or when it was terminated forcefully using fplThreadTerminate() .

Warning: Do not call

fplThreadTerminate() to stop or release a Thread! Let the thread exit naturally.

Waiting/Joining for Threads to Exit

Wait for a single Thread to Exit

Call fplThreadWaitForOne() with a pointer to fplThreadHandle and a fplTimeoutValue argument, to wait for a single Thread to finish.

// Wait until the thread is finished
(thread, );

// ... or

// Wait at max for 5 seconds to finish the thread
(thread, 5000);

Wait for any Thread to Exit

Call fplThreadWaitForAny() to wait until at least for one Thread to finish.

Example, default thread handle array:

 **threads; // Thread handle array already initialized

// Wait until one of the threads is finished
(threads, numOfThreads, sizeof( *), );

// ... or

// Wait at max for 5 seconds to finish at least one of the threads -> default stride
(threads, numOfThreads, sizeof( *), 5000);

Example, custom struct with stored thread handle:

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

MyCustomStruct *customThreads; // Struct array already initialized

 **firstPointerToThread = &customThreads[0].thread;

// Wait until one of the threads is finished
(firstPointerToThread, numOfThreads, sizeof(MyCustomStruct), );

// ... or

// Wait at max for 5 seconds to finish at least one of the threads -> default stride
(firstPointerToThread, numOfThreads, sizeof(MyCustomStruct), 5000);

Wait for all Threads to Exit

Call fplThreadWaitForAll() to wait for all Threads to be finished.

Example, default thread handle array:

 **threads; // Thread handle array already initialized

// Wait until all of the threads are finished
(threads, numOfThreads, sizeof( *), );

// ... or

// Wait at max for 5 seconds to finish all threads
(threads, numOfThreads, sizeof( *), 5000);

Example, custom struct with stored thread handle:

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

MyCustomStruct *customThreads; // Struct array already initialized

 **firstPointerToThread = &customThreads[0].thread;

// Wait until all of the threads are finished
(threads, numOfThreads, sizeof(MyCustomStruct), );

// ... or

// Wait at max for 5 seconds to finish all threads
(threads, numOfThreads, sizeof(MyCustomStruct), 5000);

Terminate a thread

Call fplThreadTerminate() with a pointer to fplThreadHandle as an argument, to forcefully terminate a thread.

Note: Using this will almost immediately terminate the thread and releases its resources.

It is safe to call this when a thread is already terminated.

Query the Thread State

Call fplGetThreadState() with a pointer to fplThreadHandle as an argument, to query the current state. If a thread is stopped or in the process of getting stopped, it will return fplThreadState_Stopped or fplThreadState_Stopping respectively. If a thread is started or in the process of getting started, it will return fplThreadState_Running or fplThreadState_Starting respectively.

Notes

Note: Your code should always ensure that it will exit eventually. You can use

Synchronization methods to achieve this.

It is bad practice to "Terminate" a thread, you should design your code to let threads end naturally.