lib/libstdthreads/thrd_create.3

   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
 112 As of
 113 .St -isoC-2011 ,
 114 the C standard includes an API for writing multithreaded applications.
 115 Since POSIX.1 already includes a threading API that is used by virtually
 116 any multithreaded application, the interface provided by the C standard
 117 can be considered superfluous.
 118 .Pp
 119 In this implementation, the threading interface is therefore implemented
 120 as a light-weight layer on top of existing interfaces.
 121 The functions to which these routines are mapped, are listed in the
 122 following table.
 123 Please refer to the documentation of the POSIX equivalent functions for
 124 more 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
 154 The
 155 .Fn thrd_exit
 156 function returns an integer value to the thread calling
 157 .Fn thrd_join ,
 158 whereas the
 159 .Fn pthread_exit
 160 function uses a pointer.
 161 .Pp
 162 The mutex created by
 163 .Fn mtx_init
 164 can be of
 165 .Fa type
 166 .Dv mtx_plain
 167 or
 168 .Dv mtx_timed
 169 to distinguish between a mutex that supports
 170 .Fn mtx_timedlock .
 171 This type can be
 172 .Em or'd
 173 with
 174 .Dv mtx_recursive
 175 to create a mutex that allows recursive acquisition.
 176 These properties are normally set using
 177 .Fn pthread_mutex_init Ns 's
 178 .Fa attr
 179 parameter.
 180 .Sh RETURN VALUES
 181 If 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
 198 and
 199 .Fn tss_set
 200 functions return
 201 .Dv thrd_success .
 202 Otherwise an error code will be returned to indicate the error.
 203 .Pp
 204 The
 205 .Fn thrd_current
 206 function returns the thread ID of the calling thread.
 207 .Pp
 208 The
 209 .Fn tss_get
 210 function returns the thread-specific data value associated with the
 211 given
 212 .Fa key .
 213 If no thread-specific data value is associated with
 214 .Fa key ,
 215 then the value NULL is returned.
 216 .Sh ERRORS
 217 The
 218 .Fn cnd_init
 219 and
 220 .Fn thrd_create
 221 functions will fail if:
 222 .Bl -tag -width thrd_timedout
 223 .It Dv thrd_nomem
 224 The system has insufficient memory.
 225 .El
 226 .Pp
 227 The
 228 .Fn cnd_timedwait
 229 and
 230 .Fn mtx_timedlock
 231 functions will fail if:
 232 .Bl -tag -width thrd_timedout
 233 .It Dv thrd_timedout
 234 The system time has reached or exceeded the time specified in
 235 .Fa ts
 236 before the operation could be completed.
 237 .El
 238 .Pp
 239 The
 240 .Fn mtx_trylock
 241 function will fail if:
 242 .Bl -tag -width thrd_timedout
 243 .It Dv thrd_busy
 244 The mutex is already locked.
 245 .El
 246 .Pp
 247 In all other cases, these functions may fail by returning general error
 248 code
 249 .Dv thrd_error .
 250 .Sh SEE ALSO
 251 .Xr nanosleep 2 ,
 252 .Xr pthread 3
 253 .Sh STANDARDS
 254 These functions are expected to conform to
 255 .St -isoC-2011 .
 256 .Sh HISTORY
 257 These functions appeared in
 258 .Fx 10.0 .
 259 .Sh AUTHORS
 260 .An Ed Schouten Aq ed@FreeBSD.org