1.\" Copyright (c) 2011 Ed Schouten <ed@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd December 26, 2011 28.Dt THRD_CREATE 3 29.Os 30.Sh NAME 31.Nm call_once , 32.Nm cnd_broadcast , 33.Nm cnd_destroy , 34.Nm cnd_init , 35.Nm cnd_signal , 36.Nm cnd_timedwait , 37.Nm cnd_wait , 38.Nm mtx_destroy , 39.Nm mtx_init , 40.Nm mtx_lock , 41.Nm mtx_timedlock , 42.Nm mtx_trylock , 43.Nm mtx_unlock , 44.Nm thrd_create , 45.Nm thrd_current , 46.Nm thrd_detach , 47.Nm thrd_equal , 48.Nm thrd_exit , 49.Nm thrd_join , 50.Nm thrd_sleep , 51.Nm thrd_yield , 52.Nm tss_create , 53.Nm tss_delete , 54.Nm tss_get , 55.Nm tss_set 56.Nd C11 threads interface 57.Sh LIBRARY 58.Lb libstdthreads 59.Sh SYNOPSIS 60.In threads.h 61.Ft void 62.Fn call_once "once_flag *flag" "void (*func)(void)" 63.Ft int 64.Fn cnd_broadcast "cnd_t *cond" 65.Ft void 66.Fn cnd_destroy "cnd_t *cond" 67.Ft int 68.Fn cnd_init "cnd_t *cond" 69.Ft int 70.Fn cnd_signal "cnd_t *cond" 71.Ft int 72.Fn cnd_timedwait "cnd_t * restrict cond" "mtx_t * restrict mtx" "const struct timespec * restrict ts" 73.Ft int 74.Fn cnd_wait "cnd_t *cond" "mtx_t *mtx" 75.Ft void 76.Fn mtx_destroy "mtx_t *mtx" 77.Ft int 78.Fn mtx_init "mtx_t *mtx" "int type" 79.Ft int 80.Fn mtx_lock "mtx_t *mtx" 81.Ft int 82.Fn mtx_timedlock "mtx_t * restrict mtx" "const struct timespec * restrict ts" 83.Ft int 84.Fn mtx_trylock "mtx_t *mtx" 85.Ft int 86.Fn mtx_unlock "mtx_t *mtx" 87.Ft int 88.Fn thrd_create "thrd_t *thr" "int (*func)(void *)" "void *arg" 89.Ft thrd_t 90.Fn thrd_current "void" 91.Ft int 92.Fn thrd_detach "thrd_t thr" 93.Ft int 94.Fn thrd_equal "thrd_t thr0" "thrd_t thr1" 95.Ft _Noreturn void 96.Fn thrd_exit "int res" 97.Ft int 98.Fn thrd_join "thrd_t thr" "int *res" 99.Ft int 100.Fn thrd_sleep "const struct timespec *duration" "struct timespec *remaining" 101.Ft void 102.Fn thrd_yield "void" 103.Ft int 104.Fn tss_create "tss_t *key" "void (*dtor)(void *)" 105.Ft void 106.Fn tss_delete "tss_t key" 107.Ft void * 108.Fn tss_get "tss_t key" 109.Ft int 110.Fn tss_set "tss_t key" "void *val" 111.Sh DESCRIPTION 112As of 113.St -isoC-2011 , 114the C standard includes an API for writing multithreaded applications. 115Since POSIX.1 already includes a threading API that is used by virtually 116any multithreaded application, the interface provided by the C standard 117can be considered superfluous. 118.Pp 119In this implementation, the threading interface is therefore implemented 120as a light-weight layer on top of existing interfaces. 121The functions to which these routines are mapped, are listed in the 122following table. 123Please refer to the documentation of the POSIX equivalent functions for 124more information. 125.Bl -column ".Fn mtx_timedlock" ".Xr pthread_mutex_timedlock 3" -offset indent 126.It Em Function Ta Em POSIX equivalent 127.It Fn call_once Ta Xr pthread_once 3 128.It Fn cnd_broadcast Ta Xr pthread_cond_broadcast 3 129.It Fn cnd_destroy Ta Xr pthread_cond_destroy 3 130.It Fn cnd_init Ta Xr pthread_cond_init 3 131.It Fn cnd_signal Ta Xr pthread_cond_signal 3 132.It Fn cnd_timedwait Ta Xr pthread_cond_timedwait 3 133.It Fn cnd_wait Ta Xr pthread_cond_wait 3 134.It Fn mtx_destroy Ta Xr pthread_mutex_destroy 3 135.It Fn mtx_init Ta Xr pthread_mutex_init 3 136.It Fn mtx_lock Ta Xr pthread_mutex_lock 3 137.It Fn mtx_timedlock Ta Xr pthread_mutex_timedlock 3 138.It Fn mtx_trylock Ta Xr pthread_mutex_trylock 3 139.It Fn mtx_unlock Ta Xr pthread_mutex_unlock 3 140.It Fn thrd_create Ta Xr pthread_create 3 141.It Fn thrd_current Ta Xr pthread_self 3 142.It Fn thrd_detach Ta Xr pthread_detach 3 143.It Fn thrd_equal Ta Xr pthread_equal 3 144.It Fn thrd_exit Ta Xr pthread_exit 3 145.It Fn thrd_join Ta Xr pthread_join 3 146.It Fn thrd_sleep Ta Xr nanosleep 2 147.It Fn thrd_yield Ta Xr pthread_yield 3 148.It Fn tss_create Ta Xr pthread_key_create 3 149.It Fn tss_delete Ta Xr pthread_key_delete 3 150.It Fn tss_get Ta Xr pthread_getspecific 3 151.It Fn tss_set Ta Xr pthread_setspecific 3 152.El 153.Sh DIFFERENCES WITH POSIX EQUIVALENTS 154The 155.Fn thrd_exit 156function returns an integer value to the thread calling 157.Fn thrd_join , 158whereas the 159.Fn pthread_exit 160function uses a pointer. 161.Pp 162The mutex created by 163.Fn mtx_init 164can be of 165.Fa type 166.Dv mtx_plain 167or 168.Dv mtx_timed 169to distinguish between a mutex that supports 170.Fn mtx_timedlock . 171This type can be 172.Em or'd 173with 174.Dv mtx_recursive 175to create a mutex that allows recursive acquisition. 176These properties are normally set using 177.Fn pthread_mutex_init Ns 's 178.Fa attr 179parameter. 180.Sh RETURN VALUES 181If successful, the 182.Fn cnd_broadcast , 183.Fn cnd_init , 184.Fn cnd_signal , 185.Fn cnd_timedwait , 186.Fn cnd_wait , 187.Fn mtx_init , 188.Fn mtx_lock , 189.Fn mtx_timedlock , 190.Fn mtx_trylock , 191.Fn mtx_unlock , 192.Fn thrd_create , 193.Fn thrd_detach , 194.Fn thrd_equal , 195.Fn thrd_join , 196.Fn thrd_sleep , 197.Fn tss_create 198and 199.Fn tss_set 200functions return 201.Dv thrd_success . 202Otherwise an error code will be returned to indicate the error. 203.Pp 204The 205.Fn thrd_current 206function returns the thread ID of the calling thread. 207.Pp 208The 209.Fn tss_get 210function returns the thread-specific data value associated with the 211given 212.Fa key . 213If no thread-specific data value is associated with 214.Fa key , 215then the value NULL is returned. 216.Sh ERRORS 217The 218.Fn cnd_init 219and 220.Fn thrd_create 221functions will fail if: 222.Bl -tag -width thrd_timedout 223.It Dv thrd_nomem 224The system has insufficient memory. 225.El 226.Pp 227The 228.Fn cnd_timedwait 229and 230.Fn mtx_timedlock 231functions will fail if: 232.Bl -tag -width thrd_timedout 233.It Dv thrd_timedout 234The system time has reached or exceeded the time specified in 235.Fa ts 236before the operation could be completed. 237.El 238.Pp 239The 240.Fn mtx_trylock 241function will fail if: 242.Bl -tag -width thrd_timedout 243.It Dv thrd_busy 244The mutex is already locked. 245.El 246.Pp 247In all other cases, these functions may fail by returning general error 248code 249.Dv thrd_error . 250.Sh SEE ALSO 251.Xr nanosleep 2 , 252.Xr pthread 3 253.Sh STANDARDS 254These functions are expected to conform to 255.St -isoC-2011 . 256.Sh HISTORY 257These functions appeared in 258.Fx 10.0 . 259.Sh AUTHORS 260.An Ed Schouten Aq Mt ed@FreeBSD.org 261