paul_threads.h

Includes:

<stddef.h>
<stdbool.h>
<stdlib.h>
<threads.h>
<stdatomic.h>
<windows.h>
<pthread.h>

Introduction

Cross-platform thread pool and job queue implementation for C/C++.

Discussion

Implementation is included when PAUL_THREADS_IMPLEMENTATION or PAUL_IMPLEMENTATION is defined.

Updated:: Saturday, July 19, 2025

Functions

thrd_pool_create: Create a thread pool
thrd_pool_destroy: Destroy the thread pool
thrd_pool_get_active_count: Get the number of active threads in the thread pool
thrd_pool_get_queue_size: Get the size of the job queue in the thread pool
thrd_pool_get_thread_count: Get the number of threads in the thread pool
thrd_pool_submit: Submit a job to the thread pool
thrd_pool_wait: Wait for all jobs in the thread pool to complete

thrd_pool_create

Create a thread pool

thrd_pool_t* thrd_pool_create(
    size_t num_threads,
    size_t max_queue_size);

Parameters

num_threads: Number of worker threads
max_queue_size: Maximum size of the job queue

Return Value

Returns a pointer to the created thread pool, or NULL on failure

thrd_pool_destroy

Destroy the thread pool

void thrd_pool_destroy(
    thrd_pool_t *pool);

Parameters

pool: Pointer to the thread pool

thrd_pool_get_active_count

Get the number of active threads in the thread pool

size_t thrd_pool_get_active_count(
    thrd_pool_t *pool);

Parameters

pool: Pointer to the thread pool

Return Value

Returns the number of active threads

thrd_pool_get_queue_size

Get the size of the job queue in the thread pool

size_t thrd_pool_get_queue_size(
    thrd_pool_t *pool);

Parameters

pool: Pointer to the thread pool

Return Value

Returns the size of the job queue

thrd_pool_get_thread_count

Get the number of threads in the thread pool

size_t thrd_pool_get_thread_count(
    thrd_pool_t *pool);

Parameters

pool: Pointer to the thread pool

Return Value

Returns the number of threads in the pool

thrd_pool_submit

Submit a job to the thread pool

int thrd_pool_submit(
    thrd_pool_t *pool,
    void (*function)(
        void*),
    void *arg,
    void (*cleanup)(
        void*));

Parameters

pool: Pointer to the thread pool
function: Pointer to the function to execute
arg: Argument to pass to the function
cleanup: Optional cleanup function

Return Value

Returns thrd_success on success, thrd_error on failure

thrd_pool_wait

Wait for all jobs in the thread pool to complete

void thrd_pool_wait(
    thrd_pool_t *pool);

Parameters

pool: Pointer to the thread pool

Typedefs

job_node_t
job_queue_t
job_t
thrd_pool_t

job_node_t

typedef struct job_node { 
    job_t job; 
    struct job_node *next; 
} job_node_t;

Fields

job: The job contained in this node
next: Pointer to the next node

Discussion

Node structure for the job queue

job_queue_t

typedef struct job_queue { 
    job_node_t *head; 
    job_node_t *tail; 
    mtx_t mutex; 
    cnd_t not_empty; 
    size_t size; 
    size_t max_size; 
    bool shutdown; 
} job_queue_t;

Fields

head: Pointer to the head of the job queue
tail: Pointer to the tail of the job queue
mutex: Mutex for thread safety
not_empty: Condition variable for waiting on empty queue
size: Current number of jobs in the queue
max_size: Maximum size of the queue
shutdown: Flag indicating if the queue is shutting down

Discussion

Job queue structure for thread pool

job_t

typedef struct job { 
    void (*function)(
        void *arg); 
    void *arg; 
    void (*cleanup)(
        void *arg); // Optional cleanup function 
} job_t;

Fields

function: Pointer to the function to execute
arg: Argument to pass to the function
cleanup: Optional cleanup function

Discussion

Job structure for thread pool tasks

thrd_pool_t

typedef struct { 
    thrd_t *threads; 
    size_t num_threads; 
    job_queue_t job_queue; 
    atomic_bool shutdown; 
    atomic_size_t active_threads; 
    mtx_t pool_mutex; 
    cnd_t all_threads_idle; 
} thrd_pool_t;

Fields

threads: Array of worker threads
num_threads: Number of worker threads
job_queue: The job queue
shutdown: Atomic flag indicating if the pool is shutting down
active_threads: Atomic count of active threads
pool_mutex: Mutex for pool operations
all_threads_idle: Condition variable for waiting on all threads idle

Discussion

Thread pool structure

Last Updated: Saturday, July 19, 2025