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