THRD_CREATE(3) BSD Library Functions Manual THRD_CREATE(3)
NAME
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
library ``libstdthreads''
SYNOPSIS
#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);
DESCRIPTION
As of ISO/IEC 9899:2011 (``ISO C11''), 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 superflu-
ous.
In this implementation, the threading interface is therefore implemented as a light-weight layer on top of existing interfaces. The func-
tions to which these routines are mapped, are listed in the following table. Please refer to the documentation of the POSIX equivalent func-
tions 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)
DIFFERENCES WITH POSIX EQUIVALENTS
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.
RETURN VALUES
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.
ERRORS
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.
SEE ALSO
nanosleep(2), pthread(3)
STANDARDS
These functions are expected to conform to ISO/IEC 9899:2011 (``ISO C11'').
HISTORY
These functions appeared in FreeBSD 10.0.
AUTHORS
Ed Schouten <ed@FreeBSD.org>
BSD
December 26, 2011 BSD