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));)(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);)(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 *));

     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)
           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>

FreeBSD 13.1-RELEASE-p6        December 26, 2011       FreeBSD 13.1-RELEASE-p6