stdx_thread.h

home

STDX - Multithreading Utilities Part of the STDX General Purpose C Library by marciovmf License: MIT https://github.com/marciovmf/stdx

Overview

Designed to abstract platform-specific APIs (e.g., pthreads, Win32) behind a consistent and lightweight int32_terface. This header provides functions for:

  • Thread creation and joining
  • Mutexes and condition variables
  • Sleep/yield utilities
  • A thread pool for concurrent task execution

How to compile

To compile the implementation define X_IMPL_THREAD in one source file before including this header.

To customize how this module allocates memory, define X_THREAD_ALLOC / X_THREAD_FREE before including.

Macro

X_THREADING_VERSION_MAJOR

#define X_THREADING_VERSION_MAJOR 1
Macro

X_THREADING_VERSION_MINOR

#define X_THREADING_VERSION_MINOR 0
Macro

X_THREADING_VERSION_PATCH

#define X_THREADING_VERSION_PATCH 0
Typedef

XThreadTask

typedef void(*XThreadTask)(void *arg);
Typedef

XThreadFunc

typedef void *(*XThreadFunc)(void *);
Struct

XThread

typedef struct XThread XThread;
Struct

XMutex

typedef struct XMutex XMutex;
Struct

XCondVar

typedef struct XCondVar XCondVar;
Struct

XThreadPool

typedef struct XThreadPool XThreadPool;
Struct

XTask

typedef struct XTask XTask;
Function

x_thread_create

Create and start a new thread.

int32_t x_thread_create(
 XThread **t,
 XThreadFunc func,
 void *arg
);

Parameters

XThread **t
Output pointer that receives the created thread handle.
XThreadFunc func
Thread entry function.
void *arg
User argument passed to func.

Returns

0 on success, non-zero on failure.

Function

x_thread_join

Wait for a thread to finish execution.

void x_thread_join(XThread *t);

Parameters

XThread *t
Thread handle.
Function

x_thread_destroy

Destroy a thread handle and release its resources.

void x_thread_destroy(XThread *t);

Parameters

XThread *t
Thread handle.
Function

x_thread_mutex_init

Create a mutex.

int32_t x_thread_mutex_init(XMutex **m);

Parameters

XMutex **m
Output pointer that receives the created mutex handle.

Returns

0 on success, non-zero on failure.

Function

x_thread_mutex_lock

Lock a mutex, blocking until it becomes available.

void x_thread_mutex_lock(XMutex *m);

Parameters

XMutex *m
Mutex handle.
Function

x_thread_mutex_unlock

Unlock a mutex.

void x_thread_mutex_unlock(XMutex *m);

Parameters

XMutex *m
Mutex handle.
Function

x_thread_mutex_destroy

Destroy a mutex and release its resources.

void x_thread_mutex_destroy(XMutex *m);

Parameters

XMutex *m
Mutex handle.
Function

x_thread_condvar_init

Create a condition variable.

int32_t x_thread_condvar_init(XCondVar **cv);

Parameters

XCondVar **cv
Output pointer that receives the created condition variable handle.

Returns

0 on success, non-zero on failure.

Function

x_thread_condvar_wait

Wait on a condition variable.

void x_thread_condvar_wait(
 XCondVar *cv,
 XMutex *m
);

Parameters

XCondVar *cv
Condition variable handle.
XMutex *m
Mutex that will be atomically released while waiting and re-acquired before returning.
Function

x_thread_condvar_signal

Wake one thread waiting on a condition variable.

void x_thread_condvar_signal(XCondVar *cv);

Parameters

XCondVar *cv
Condition variable handle.
Function

x_thread_condvar_broadcast

Wake all threads waiting on a condition variable.

void x_thread_condvar_broadcast(XCondVar *cv);

Parameters

XCondVar *cv
Condition variable handle.
Function

x_thread_condvar_destroy

Destroy a condition variable and release its resources.

void x_thread_condvar_destroy(XCondVar *cv);

Parameters

XCondVar *cv
Condition variable handle.
Function

x_thread_sleep_ms

Sleep the current thread for at least the given number of milliseconds.

void x_thread_sleep_ms(int ms);

Parameters

int ms
Duration in milliseconds.
Function

x_thread_yield

Yield execution to allow other threads to run.

void x_thread_yield(void);
Function

x_threadpool_create

Create a thread pool with a fixed number of worker threads.

XThreadPool * x_threadpool_create(int num_threads);

Parameters

int num_threads
Number of worker threads to start.

Returns

Thread pool handle, or NULL on failure.

Function

x_threadpool_enqueue

Enqueue a task for execution by the thread pool.

int32_t x_threadpool_enqueue(
 XThreadPool *pool,
 XThreadTask fn,
 void *arg
);

Parameters

XThreadPool *pool
Thread pool handle.
XThreadTask fn
Task function to execute.
void *arg
User argument passed to fn.

Returns

0 on success, non-zero on failure.

Function

x_threadpool_destroy

Destroy a thread pool and release its resources.

void x_threadpool_destroy(XThreadPool *pool);

Parameters

XThreadPool *pool
Thread pool handle.
Macro

X_THREAD_ALLOC

Internal macro for allocating memory. To override how this header allocates memory, define this macro with a different implementation before including this header.

#define X_THREAD_ALLOC(sz) malloc(sz)

Parameters

sz
The size of memory to alloc.
Macro

X_THREAD_FREE

Internal macro for freeing memory. To override how this header frees memory, define this macro with a different implementation before including this header.

#define X_THREAD_FREE(p) free(p)

Parameters

p
The address of memory region to free.
Struct

XThreadWrapper

struct XThreadWrapper{
  XThreadFunc func;
  void *arg;
};
Function

x_thread_mutexinit

int32_t x_thread_mutexinit(XMutex **m);
Macro

THREADPOOL_MAGIC

#define THREADPOOL_MAGIC 0xDEADBEEF