Manual Pages  — THRD_CREATE

call_once, cnd_broadcast, cnd_destroy, cnd_init, cnd_signal, cnd_timedwait, cnd_wait, mtx_destroy, mtx_init, mtx_lock, mtx_timedlock, mtx_trylock, mtx_unlock, thrd_create, thrd_current, thrd_detach, thrd_equal, thrd_exit, thrd_join, thrd_sleep, thrd_yield, tss_create, tss_delete, tss_get, tss_set – C11 threads interface

LIBRARY SYNOPSIS DESCRIPTION DIFFERENCES WITH POSIX EQUIVALENTS RETURN VALUES ERRORS SEE ALSO STANDARDS HISTORY AUTHORS

libstdthreads

#include <threads.h>

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

int
cnd_broadcast(cnd_t *cond);

void
cnd_destroy(cnd_t *cond);

int
cnd_init(cnd_t *cond);

int
cnd_signal(cnd_t *cond);

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

int
cnd_wait(cnd_t *cond, mtx_t *mtx);

void
mtx_destroy(mtx_t *mtx);

int
mtx_init(mtx_t *mtx, int type);

int
mtx_lock(mtx_t *mtx);

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

int
mtx_trylock(mtx_t *mtx);

int
mtx_unlock(mtx_t *mtx);

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

thrd_t
thrd_current(void);

int
thrd_detach(thrd_t thr);

int
thrd_equal(thrd_t thr0, thrd_t thr1);

_Noreturn void
thrd_exit(int res);

int
thrd_join(thrd_t thr, int *res);

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

void
thrd_yield(void);

int
tss_create(tss_t *key, void (*dtor)(void *));

void
tss_delete(tss_t key);

void *
tss_get(tss_t key);

int
tss_set(tss_t key, void *val);

As of ISO/IEC , the C standard includes an API for writing multithreaded applications. Since POSIX.1 already includes a threading API that is used by virtually any multithreaded application, the interface provided by the C standard can be considered superfluous.

In this implementation, the threading interface is therefore implemented as a light-weight layer on top of existing interfaces. The functions to which these routines are mapped, are listed in the following table. Please refer to the documentation of the POSIX equivalent functions for more information.

Function	POSIX equivalent
call_once()	pthread_once(3)
cnd_broadcast()	pthread_cond_broadcast(3)
cnd_destroy()	pthread_cond_destroy(3)
cnd_init()	pthread_cond_init(3)
cnd_signal()	pthread_cond_signal(3)
cnd_timedwait()	pthread_cond_timedwait(3)
cnd_wait()	pthread_cond_wait(3)
mtx_destroy()	pthread_mutex_destroy(3)
mtx_init()	pthread_mutex_init(3)
mtx_lock()	pthread_mutex_lock(3)
mtx_timedlock()	pthread_mutex_timedlock(3)
mtx_trylock()	pthread_mutex_trylock(3)
mtx_unlock()	pthread_mutex_unlock(3)
thrd_create()	pthread_create(3)
thrd_current()	pthread_self(3)
thrd_detach()	pthread_detach(3)
thrd_equal()	pthread_equal(3)
thrd_exit()	pthread_exit(3)
thrd_join()	pthread_join(3)
thrd_sleep()	nanosleep(2)
thrd_yield()	pthread_yield(3)
tss_create()	pthread_key_create(3)
tss_delete()	pthread_key_delete(3)
tss_get()	pthread_getspecific(3)
tss_set()	pthread_setspecific(3)

The thrd_exit() function returns an integer value to the thread calling thrd_join(), whereas the pthread_exit() function uses a pointer.

The mutex created by mtx_init() can be of type mtx_plain or mtx_timed to distinguish between a mutex that supports mtx_timedlock(). This type can be or'd with mtx_recursive to create a mutex that allows recursive acquisition. These properties are normally set using pthread_mutex_init()'s attr parameter.

If successful, the cnd_broadcast(), cnd_init(), cnd_signal(), cnd_timedwait(), cnd_wait(), mtx_init(), mtx_lock(), mtx_timedlock(), mtx_trylock(), mtx_unlock(), thrd_create(), thrd_detach(), thrd_equal(), thrd_join(), thrd_sleep(), tss_create() and tss_set() functions return thrd_success. Otherwise an error code will be returned to indicate the error.

The thrd_current() function returns the thread ID of the calling thread.

The tss_get() function returns the thread-specific data value associated with the given key. If no thread-specific data value is associated with key, then the value NULL is returned.

The cnd_init() and thrd_create() functions will fail if:

thrd_nomem	The system has insufficient memory.

The cnd_timedwait() and mtx_timedlock() functions will fail if:

thrd_timedout
	The system time has reached or exceeded the time specified in ts before the operation could be completed.

The mtx_trylock() function will fail if:

thrd_busy	The mutex is already locked.

In all other cases, these functions may fail by returning general error code thrd_error.

These functions are expected to conform to ISO/IEC .

These functions appeared in FreeBSD 10.0 .

Ed Schouten <Mt ed@FreeBSD.org>