C11 threading functionality. 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>

Macros
#define	thrd_success 0
	Success. More...

#define	thrd_error -1
	Uncategorized error. More...

#define	thrd_timedout -2
	Time out error. More...

#define	thrd_busy -3
	Resource busy. More...

#define	thrd_nomem -4
	Out of memory. More...

#define	ONCE_FLAG_INIT KTHREAD_ONCE_INIT
	Macro to initiallize a once_flag object. More...

#define	mtx_plain (1 << 0)
	Plain mutex. More...

#define	mtx_recursive (1 << 1)
	Recursive mutex. More...

#define	mtx_timed (1 << 2)
	Mutex supporting the mtx_timedlock function. More...

#define	TSS_DTOR_ITERATIONS 1
	Maximum number of iterations over TSS destructors. More...

Typedefs
typedef kthread_once_t	once_flag
	Object type backing call_once. More...

typedef mutex_t	mtx_t
	C11 mutual exclusion lock type. More...

typedef condvar_t	cnd_t
	C11 condition variable type. More...

typedef kthread_t *	thrd_t
	C11 thread identifier type. More...

typedef int(*	thrd_start_t )(void *)
	C11 thread start function type. More...

typedef kthread_key_t	tss_t
	C11 thread-specific storage type. More...

typedef void(*	tss_dtor_t )(void *)
	C11 thread-specific storage destructor type. More...

Functions
void	call_once (once_flag flag, void(func)(void))
	Call a function one time, no matter how many threads try. More...

void	mtx_destroy (mtx_t *mtx)
	Deinitialize a mutex lock. More...

int	mtx_init (mtx_t *mtx, int type)
	Initialize a mutex lock. More...

int	mtx_lock (mtx_t *mtx)
	Lock a mutex lock. More...

int	mtx_timedlock (mtx_t restrict mtx, const struct timespec restrict ts)
	Lock a mutex lock with a timeout. More...

int	mtx_trylock (mtx_t *mtx)
	Attempt to acquire a mutex lock. More...

int	mtx_unlock (mtx_t *mtx)
	Unlock a previously acquired lock. More...

int	cnd_broadcast (cnd_t *cond)
	Broadcast to all threads locked on a condition variable. More...

void	cnd_destroy (cnd_t *cond)
	Deinitialize a condition variable. More...

int	cnd_init (cnd_t *cond)
	Initialize a condition variable. More...

int	cnd_signal (cnd_t *cond)
	Signal one thread locked on a condition variable. More...

int	cnd_timedwait (cnd_t restrict cond, mtx_t restrict mtx, const struct timespec *restrict ts)
	Wait on a condition variable (with a timeout). More...

int	cnd_wait (cnd_t cond, mtx_t mtx)
	Wait on a condition variable. More...

int	thrd_create (thrd_t thr, thrd_start_t func, void arg)
	Create and start a new thread. More...

thrd_t	thrd_current (void)
	Return the identifier of the currently running thread. More...

int	thrd_detach (thrd_t thr)
	Detach a running thread. More...

int	thrd_equal (thrd_t thr0, thrd_t thr1)
	Compare two threads for equality. More...

_Noreturn void	thrd_exit (int res)
	Terminate the current thread immediately. More...

int	thrd_join (thrd_t thr, int *res)
	Join a running thread. More...

int	thrd_sleep (const struct timespec duration, struct timespec remaining)
	Put the currently running thread to sleep. More...

void	thrd_yield (void)
	Yield the current thread's timeslice. More...

int	tss_create (tss_t *key, tss_dtor_t dtor)
	Create a thread-specific storage pointer. More...

void	tss_delete (tss_t key)
	Free resources associated with a thread-specific storage key. More...

void *	tss_get (tss_t key)
	Retrieve the value associated with a thread-specific storage key. More...

int	tss_set (tss_t key, void *val)
	Set the value associated with a thread-specific storage key. More...

Detailed Description

C11 threading functionality.

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

Macro Definition Documentation

#define ONCE_FLAG_INIT KTHREAD_ONCE_INIT

Macro to initiallize a once_flag object.

#define TSS_DTOR_ITERATIONS 1

Maximum number of iterations over TSS destructors.

This macro defines the maximum number of iterations that will be performed over the destructors for thread-specific storage objects when a thread terminates.

Typedef Documentation

typedef condvar_t cnd_t

C11 condition variable type.

This type holds an identifier for a condition variable object that is to be used with C11 threading support.

typedef mutex_t mtx_t

C11 mutual exclusion lock type.

This type holds an identifier for a mutual exclusion (mutex) lock to be used with C11 threading support.

typedef kthread_once_t once_flag

Object type backing call_once.

This object type holds a flag that is used by the call_once function to call a function one time. It should always be initialized with the ONCE_FLAG_INIT macro.

typedef int(* thrd_start_t)(void *)

C11 thread start function type.

This is a function pointer type representing a function used to begin a thread. The thread exits when the function returns or calls thrd_exit().

typedef kthread_t* thrd_t

C11 thread identifier type.

This type holds an identifier for a C11 thread.

typedef void(* tss_dtor_t)(void *)

C11 thread-specific storage destructor type.

This is a function pointer type which describes a destructor for a thread-specific storage object.

typedef kthread_key_t tss_t

C11 thread-specific storage type.

This type holds a thread-specific storage identifier, which allows a value to be associated with it for each and every thread running.

Function Documentation

void call_once	(	once_flag *	flag,
		void(*)(void)	func
	)

Call a function one time, no matter how many threads try.

This function uses the once_flag object passed in to ensure that a given function is called exactly once, regardless of how many threads attempt to call through the once_flag.

Parameters

flag	The once_flag to run against.
func	The function to call.

int cnd_broadcast ( cnd_t * cond )

Broadcast to all threads locked on a condition variable.

This function wakes all threads that are blocked on the condition variable cond at the time of the call. If no threads are currently blocked on cond, this call does nothing.

Parameters

cond	The condition variable to signal.

Return values

thrd_success	On success.
thrd_error	If the request cannot be honored.

void cnd_destroy ( cnd_t * cond )

Deinitialize a condition variable.

This function cleans up all resources associated with the given condition variable. You must ensure that no threads are currently blocked on the condition variable before calling this function.

Parameters

cond	The condition variable to deinitialize.

Note: Deinitializing a condition variable that is currently being waited on by threads results in undefined behavior.

int cnd_init ( cnd_t * cond )

Initialize a condition variable.

This function initializes the specified condition variable for use.

Parameters

cond	The condition variable to signal.

Return values

thrd_success	On success.
thrd_nomem	If memory cannot be allocated for the new condition variable.
thrd_error	If the request cannot be honored for some other reason.

int cnd_signal ( cnd_t * cond )

Signal one thread locked on a condition variable.

This function wakes one thread that is blocked on the condition variable cond at the time of the call. If no threads are currently blocked on cond, this call does nothing.

Parameters

cond	The condition variable to signal.

Return values

thrd_success	On success.
thrd_error	If the request cannot be honored.

int cnd_timedwait	(	cnd_t *restrict	cond,
		mtx_t *restrict	mtx,
		const struct timespec *restrict	ts
	)

Wait on a condition variable (with a timeout).

This function puts the calling thread to sleep until either the condition variable is signaled or the timeout specified expires, whichever happens first. The specified mutex must be held by the calling thread when calling this function and will be held by the thread again when it is unblocked.

Parameters

cond	The condition variable to wait on.
mtx	The mutex associated with the condition variable.
ts	The time to wait before timing out.

Return values

thrd_success	On success.
thrd_timedout	If the timeout was reached before the condition variable was signaled.
thrd_error	If the request cannot be honored for some other reason.

Note: Calling this function in an interrupt will result in an error being returned.; Although timeouts are specified in seconds and nanoseconds, the timeout will be rounded up to the nearest millisecond.

int cnd_wait	(	cnd_t *	cond,
		mtx_t *	mtx
	)

Wait on a condition variable.

This function puts the calling thread to sleep until the condition variable is signaled. The specified mutex must be held by the calling thread when calling this function and will be held by the thread again when it is unblocked.

Parameters

cond	The condition variable to wait on.
mtx	The mutex associated with the condition variable.

Return values

thrd_success	On success.
thrd_error	If the request cannot be honored.

Note: Calling this function in an interrupt will result in an error being returned.

void mtx_destroy ( mtx_t * mtx )

Deinitialize a mutex lock.

This function deinitializes a mutex lock that was previously created with mtx_init().

Parameters

mtx	The mutex to deinitialize.

int mtx_init	(	mtx_t *	mtx,
		int	type
	)

Initialize a mutex lock.

This function initializes a mutex lock of the given type for later use to protect critical sections of code.

Parameters

mtx	The mutex to initialize.
type	The type of mutex desired (see C11 mutual exclusion lock types).

Return values

thrd_success	On success.
thrd_error	If the request could not be honored.

int mtx_lock ( mtx_t * mtx )

Lock a mutex lock.

This function locks the specified mutex, preventing any other threads from obtaining the same lock.

This function will block until the lock can be obtained.

Parameters

mtx	The mutex to lock.

Return values

thrd_success	On success.
thrd_error	If the request could not be honored.

Note: Calling this function in an interrupt will result in an error being returned.

int mtx_timedlock	(	mtx_t *restrict	mtx,
		const struct timespec *restrict	ts
	)

Lock a mutex lock with a timeout.

This function locks the specified mutex, assuming that the lock can be obtained in the time period specified.

This function will block until the lock can be obtained or the timeout expires.

Parameters

mtx	The mutex to lock.
ts	The amount of time to wait before timing out.

Return values

thrd_success	On success.
thrd_error	If the request could not be honored for some other reason than a timeout.
thrd_timedout	If the timeout specified passes without obtaining the lock.

Note: Calling this function in an interrupt will result in an error being returned.; Although timeouts are specified in seconds and nanoseconds, the timeout will be rounded up to the nearest millisecond.

int mtx_trylock ( mtx_t * mtx )

Attempt to acquire a mutex lock.

This function attempts to acquire the specififed mutex and will not block if it cannot be obtained.

Parameters

mtx	The mutex to lock.

Return values

thrd_success	On success.
thrd_busy	If the lock is already locked by a thread.
thrd_error	If the request could not be honored for some other reason.

Note: This function is safe to call in an interrupt.; Always check the return value to ensure that the lock was obtained.

int mtx_unlock ( mtx_t * mtx )

Unlock a previously acquired lock.

This function releases the specified mutex lock, allowing other threads to acquire it.

Parameters

mtx	The mutex to unlock.

Return values

thrd_success	On success.
thrd_error	If the request cannot be honored.

Note: Unlocking a mutex that was not previously locked by the calling thread results in undefined behavior.

int thrd_create	(	thrd_t *	thr,
		thrd_start_t	func,
		void *	arg
	)

Create and start a new thread.

This function creates a new thread, calling the function specified. The thread is immediately added to the runnable queue of the scheduler and can start at any moment after that. The thread ends when either the function specified returns or when the thread calls thrd_exit().

Parameters

thr	Storage for the thread identifier.
func	The function to call in the new thread.
arg	Argument to pass to the function called.

Return values

thrd_success	On success.
thrd_nomem	If memory cannot be allocated to satisfy the request.
thrd_error	If the request cannot be honored for some other reason.

Note: All threads created are joinable threads by default. That means that in order to free all resources at thread termination, the thread must be joined with the thrd_join() function or detached at some point with thrd_detach().

thrd_t thrd_current ( void )

Return the identifier of the currently running thread.

Returns: The current thread's ID.

int thrd_detach ( thrd_t thr )

Detach a running thread.

This function detaches a thread, which informs the kernel that any resources associated with the thread should be freed immediately when it terminates.

Parameters

thr	The thread to detach.

Return values

thrd_success	On success.
thrd_error	If the request cannot be honored.

Note: Detaching an already detached thread has no effect.; Detaching a thread that has been joined with another thread results in undefined behavior.

int thrd_equal	(	thrd_t	thr0,
		thrd_t	thr1
	)

Compare two threads for equality.

This function checks the two two thread identifiers passed in to see if they refer to the same thread.

Parameters

thr0	The first thread to compare.
thr1	The second thread to compare.

Returns: 0 if the threads are not equal, nonzero if the threads are equal.

_Noreturn void thrd_exit ( int res )

Terminate the current thread immediately.

This function terminates the calling thread immediately, setting the return value of the thread to the value specified.

Parameters

res	The return value of the thread.

Note: This function will not return.

int thrd_join	(	thrd_t	thr,
		int *	res
	)

Join a running thread.

This function joins the current thread with the specified thread, blocking until that thread has terminated.

Parameters

thr	The thread to join with.
res	Pointer to storage for the result code of the other thread. Set to NULL if you don't care about the result value.

Return values

thrd_success	On success.
thrd_error	If the request cannot be honored.

Note: Joining with a previously detached thread results in undefined behavior.; Joining with a thread that has already been joined to another thread results in undefined behavior.; Calling this function in an interrupt will result in an error being returned.

int thrd_sleep	(	const struct timespec *	duration,
		struct timespec *	remaining
	)

Put the currently running thread to sleep.

This function puts the currently running thread to sleep for the specified duration of time, returning any left over time (if interrupted by a signal, for instance) in the second parameter.

Parameters

duration	The amount of time to sleep.
remaining	Any remaining time from the duration that the thread did not sleep for.

Returns: 0 if the requested time elapsed, a negative value otherwise.

Note: Although the duration is expressed in seconds and nanoseconds, all sleeping is done in millisecond increments. The value specified will be rounded up if it is not an even number of milliseconds.; KOS does not support signals, so remaining will only ever have a value after the function if there is some sort of error.; Calling this function in an interrupt will result in an error being returned.

void thrd_yield ( void )

Yield the current thread's timeslice.

This function immediately pauses the current thread's execution and switches to another thread in the ready queue (if there are any threads ready to execute).

Note: Calling this function in an interrupt will not have any effect.

int tss_create	(	tss_t *	key,
		tss_dtor_t	dtor
	)

Create a thread-specific storage pointer.

This function creates a thread-specific storage pointer and associates the destructor function supplied with it. After creating the pointer, each thread may associate a piece of data with the key.

Parameters

key	The key to initialize.
dtor	The destructor to associate with the key.

Return values

thrd_success	On success.
thrd_error	On failure.

void tss_delete ( tss_t key )

Free resources associated with a thread-specific storage key.

This function releases any resources used by the thread-specific storage key specified. Note that this DOES NOT call any destructors.

Parameters

key	The key to deinitialize.

void* tss_get ( tss_t key )

Retrieve the value associated with a thread-specific storage key.

This function retrieves the value associated with the specified thread-specific storage key and returns it to the caller. If no value has been set in the current thread, NULL is returned.

Parameters

key	The key to look up the value associated with.

Returns: The value associated with the key.

int tss_set	(	tss_t	key,
		void *	val
	)

Set the value associated with a thread-specific storage key.

This function sets the value to be associated with the specified thread-specific storage key, overwriting any previous keys. Note that this DOES NOT call any destructors.

Parameters

key	The key to set the value for.
val	The value to set.

Return values

thrd_success	On success.
thrd_error	If the request cannot be honored.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation