threads.h File Reference

C11 Threading API. More...

#include <sys/cdefs.h>
#include <time.h>
#include <kos/thread.h>
#include <kos/once.h>
#include <kos/mutex.h>
#include <kos/cond.h>
#include <kos/tls.h>

Go to the source code of this file.

Macros
#define	ONCE_FLAG_INIT   KTHREAD_ONCE_INIT
	Macro to initialize a once_flag object.
#define	TSS_DTOR_ITERATIONS   1
	Maximum number of iterations over TSS destructors.
Return values
C11 Thread function return values Most of the C11 thread-related functions that return a result code return one of these.
#define	thrd_success   0
	Success.
#define	thrd_error   -1
	Uncategorized error.
#define	thrd_timedout   -2
	Time out error.
#define	thrd_busy   -3
	Resource busy.
#define	thrd_nomem   -4
	Out of memory.
Mutex types
C11 mutual exclusion lock types These are the possible types of mutex locks that C11 allows for. Note that mtx_plain or mtx_recursive can be ORed with mtx_timed as well.
#define	mtx_plain   (1 << 0)
	Plain mutex.
#define	mtx_recursive   (1 << 1)
	Recursive mutex.
#define	mtx_timed   (1 << 2)
	Mutex supporting the mtx_timedlock function.

Typedefs
typedef kthread_once_t	once_flag
	Object type backing call_once.
typedef mutex_t	mtx_t
	C11 mutual exclusion lock type.
typedef condvar_t	cnd_t
	C11 condition variable type.
typedef kthread_t *	thrd_t
	C11 thread identifier type.
typedef int(*	thrd_start_t) (void *)
	C11 thread start function type.
typedef kthread_key_t	tss_t
	C11 thread-specific storage type.
typedef void(*	tss_dtor_t) (void *)
	C11 thread-specific storage destructor type.

Functions
void	call_once (once_flag *flag, void(*func)(void))
	Call a function one time, no matter how many threads try.
void	mtx_destroy (mtx_t *mtx)
	Deinitialize a mutex lock.
int	mtx_init (mtx_t *mtx, int type)
	Initialize a mutex lock.
int	mtx_lock (mtx_t *mtx)
	Lock a mutex lock.
int	mtx_timedlock (mtx_t *__RESTRICT mtx, const struct timespec *__RESTRICT ts)
	Lock a mutex lock with a timeout.
int	mtx_trylock (mtx_t *mtx)
	Attempt to acquire a mutex lock.
int	mtx_unlock (mtx_t *mtx)
	Unlock a previously acquired lock.
int	cnd_broadcast (cnd_t *cond)
	Broadcast to all threads locked on a condition variable.
void	cnd_destroy (cnd_t *cond)
	Deinitialize a condition variable.
int	cnd_init (cnd_t *cond)
	Initialize a condition variable.
int	cnd_signal (cnd_t *cond)
	Signal one thread locked on a condition variable.
int	cnd_timedwait (cnd_t *__RESTRICT cond, mtx_t *__RESTRICT mtx, const struct timespec *__RESTRICT ts)
	Wait on a condition variable (with a timeout).
int	cnd_wait (cnd_t *cond, mtx_t *mtx)
	Wait on a condition variable.
int	thrd_create (thrd_t *thr, thrd_start_t func, void *arg)
	Create and start a new thread.
thrd_t	thrd_current (void)
	Return the identifier of the currently running thread.
int	thrd_detach (thrd_t thr)
	Detach a running thread.
int	thrd_equal (thrd_t thr0, thrd_t thr1)
	Compare two threads for equality.
_Noreturn void	thrd_exit (int res)
	Terminate the current thread immediately.
int	thrd_join (thrd_t thr, int *res)
	Join a running thread.
int	thrd_sleep (const struct timespec *duration, struct timespec *remaining)
	Put the currently running thread to sleep.
void	thrd_yield (void)
	Yield the current thread's timeslice.
int	tss_create (tss_t *key, tss_dtor_t dtor)
	Create a thread-specific storage pointer.
void	tss_delete (tss_t key)
	Free resources associated with a thread-specific storage key.
void *	tss_get (tss_t key)
	Retrieve the value associated with a thread-specific storage key.
int	tss_set (tss_t key, void *val)
	Set the value associated with a thread-specific storage key.

Detailed Description

C11 Threading API.

This file contains the definitions needed for using C11 threads. The C11 standard defines a number of threading-related primitives, which we wrap neatly around KOS' built-in threading support here.

If you compile your code with a strict standard set (you use a -std= flag with GCC that doesn't start with gnu), you must use -std=c11 to use this functionality. If you don't pass a -std= flag to GCC, then you're probably fine.

Author

Lawrence Sebald