FreeBSD manual

download PDF document: cnd_wait.3.pdf

THRD_CREATE(3) FreeBSD 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 C11 Threads Library (libstdthreads, -lstdthreads)
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
_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 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)
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>
FreeBSD 14.0-RELEASE-p11 December 26, 2011 FreeBSD 14.0-RELEASE-p11