Draft:threads.h

threads.h is a C standard library header file, containing macros, types, constants and function for working with threads, mutexes and conditional variables. The header file was defined in the C11 standard as an optional header file, which was not required to be implemented in order to comply with the standard. It is currently supported by major C standard library implementations, including GNU C Standard Library and Microsoft C Runtime.

Macros

Name	Description
thread_local	Used to define a variable which is tied to a thread (storage class specifier). The variables are initialized upon the creation of the thread. This macro was removed from the standard in C23, having been made a keyword.
TSS_DTOR_ITERATIONS	An unsigned integer which defines the maximum amount of times that the destructor of the thread local memory will be called by thrd_exit.

Cosntants and Types

Name	Description
thrd_success	Indicates a successful creation or joining of a thread.
thrd_timedout	Indicates a failure to create or join the thread in a given time window.
thrd_busy	Indicates a failure to acquirethe thread resource.
thrd_nomem	Indicates a failure to complete the operation due to lack of free memory.
thrd_error	Indicates a failure to complete the operation due to an error.
thrd_t	An implementation-specific type, holding an identification or a reference to a thread.
thrd_start_t	A function of type int(*)(void*), execution starting point which will be called by thrd_create, if thread creation was successful.
mtx_plain	A mutex that a given thread can only acquire once (acquiring it more than once is an Undefined behavior.
mtx_recursive	A mutex that a given thread can acquire multiple times.
mtx_timed	A mutex that supports holding a lock for a specific amount of time. If not released after the time elapsed, an error will occur.
mtx_t	A mutex identifier
cnd_t	Conditional variable identifier
tss_t	Identifier of a thread-local storage
tss_dtor_t	A type-definition of a function pointer with the following signature: void(*)(void*), used as a Destructor of thread local storage.

Functions

Signature	Description
int thrd_create(thrd_t *thr, thrd_start_t func, void *arg)	A function to create a new thread, calling upon func and passing arg as an argument. A pointer to the created thread is stored in thr.
int thrd_equal(thrd_t lhs, thrd_t rhs)	A function that checks if two thread types reference the same thread.
thrd_t thrd_current(void)	Returns the identification of the current thread.
int thrd_sleep(const struct timespec* duration, struct timespec* remaining)	Stops the current thread for the specified duration argument, storing the amount of time remaining until it will resume execution in the remaining struct.
void thrd_yield(void)	Notifies the scheduler of the operating system that the current thread yields its time slice. The OS may prioritize and run other threads with the same priority, this thread's execution will be resumed at a later time by the OS.
_Noreturn void thrd_exit(int res)	Ends the execution of the currently running thread, setting its return code to res. Also calling all destructors of thread-local storage, until these these destructors are set to NULL or until the destructor has been called TSS_DTOR_ITERATIONS times.
int thrd_detach(thrd_t thr)	Detaches the execution of thread thr from the current thread. A thread which is not detached must be joined when it finishes executing.
int thrd_join(thrd_t thr, int *res)	The current thread will wait for thread thr to finish execution, its return code will be placed in res
int mtx_init(mtx_t* mutex, int type)	Creates a mutex with the specified type, placing a pointer to it in mutex.
int mtx_lock(mtx_t* mutex)	Stops the execution of the current thread, until it can acquire the mutex.
int mtx_timedlock(mtx_t *restrict mutex, const struct timespec *restrict time_point)	Stops the execution of the current thread until the mutex which is pointed by the mutex pointer is not released, or until the time specified in time_point will be reached.
int mtx_trylock(mtx_t *mutex)	Attempts to lock the mutex, if it is not locked already. This call is performed immediately and does not block the current thread.
int mtx_unlock(mtx_t *mutex)	Unlocks the mutex pointed to by the mutex pointer.
int mtx_destroy(mtx_t *mutex)	Destroys the mutex pointed to by the mutex pointer.
void call_once(once_flag* flag, void (*func)(void) func)	The function func will be called only once, even if attempted to be called by multiple threads.
int cnd_init(cnd_t* cond)	Creates a conditional variable, and places it in the cond pointer.
int cnd_signal(cnd_t *cond)	Unblocks a single thread which is waiting upon the conditional variable pointed to by the cond pointer.
int cnd_broadcast(cnd_t *cond)	Unblocks all threads that are waiting upon the condition variable cond at the time of the call. If no threads are blocked on cond, the function does nothing and returns thrd_success.
int cnd_wait(cnd_t* cond, mtx_t* mutex)	Releases the mutex, and blocks the conditional variable pointed to by cond until the current thread won't receive a cnd_signal or a cnd_broadcast, or until a spurious wakeup will occur.
int cnd_timedwait( cnd_t* restrict cond, mtx_t* restrict mutex, const struct timespec* restrict time_point )	Releases the mutex, and blocks the conditional variable pointed to by cond until the current thread won't receive a cnd_signal or a cnd_broadcast, until the time_point is reached, or until a spurious wakeup will occur.
void cnd_destroy(cnd_t* cond);	Destroys the condional variable.
int tss_create(tss_t* tss_key, tss_dtor_t destructor)	Creates a local thread storage pointed to by tss_key, and placing the pointer to the destructor in the tss_t type, which will then be called upon destruction of the thread.
void *tss_get(tss_t tss_key)	Retrieve the data stored in the local thread storage which is identified by the tss_key.
int tss_set(tss_t tss_id, void *val)	Sets the thread local storage identified by tss_id to val.
void tss_delete(tss_t tss_id)	Destroys the thread local storage tss_id.

Standard Library Support

Compiler	Status	Supported Since
GNU C Library	Supported	2.28
Microsoft C Runtime	Supported	Visual Studio 2022 version 17.8 Preview 2
musl	Supported	1.1.0
Bionic	Supported	API level 30

See also

• threads.h on C++ Reference