1 .\" Copyright (c) 2011 Ed Schouten <ed@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
56 .Nd C11 threads interface
62 .Fn call_once "once_flag *flag" "void (*func)(void)"
64 .Fn cnd_broadcast "cnd_t *cond"
66 .Fn cnd_destroy "cnd_t *cond"
68 .Fn cnd_init "cnd_t *cond"
70 .Fn cnd_signal "cnd_t *cond"
72 .Fn cnd_timedwait "cnd_t * restrict cond" "mtx_t * restrict mtx" "const struct timespec * restrict ts"
74 .Fn cnd_wait "cnd_t *cond" "mtx_t *mtx"
76 .Fn mtx_destroy "mtx_t *mtx"
78 .Fn mtx_init "mtx_t *mtx" "int type"
80 .Fn mtx_lock "mtx_t *mtx"
82 .Fn mtx_timedlock "mtx_t * restrict mtx" "const struct timespec * restrict ts"
84 .Fn mtx_trylock "mtx_t *mtx"
86 .Fn mtx_unlock "mtx_t *mtx"
88 .Fn thrd_create "thrd_t *thr" "int (*func)(void *)" "void *arg"
90 .Fn thrd_current "void"
92 .Fn thrd_detach "thrd_t thr"
94 .Fn thrd_equal "thrd_t thr0" "thrd_t thr1"
96 .Fn thrd_exit "int res"
98 .Fn thrd_join "thrd_t thr" "int *res"
100 .Fn thrd_sleep "const struct timespec *duration" "struct timespec *remaining"
102 .Fn thrd_yield "void"
104 .Fn tss_create "tss_t *key" "void (*dtor)(void *)"
106 .Fn tss_delete "tss_t key"
108 .Fn tss_get "tss_t key"
110 .Fn tss_set "tss_t key" "void *val"
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.
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
123 Please refer to the documentation of the POSIX equivalent functions for
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
153 .Sh DIFFERENCES WITH POSIX EQUIVALENTS
156 function returns an integer value to the thread calling
160 function uses a pointer.
169 to distinguish between a mutex that supports
175 to create a mutex that allows recursive acquisition.
176 These properties are normally set using
177 .Fn pthread_mutex_init Ns 's
202 Otherwise an error code will be returned to indicate the error.
206 function returns the thread ID of the calling thread.
210 function returns the thread-specific data value associated with the
213 If no thread-specific data value is associated with
215 then the value NULL is returned.
221 functions will fail if:
222 .Bl -tag -width thrd_timedout
224 The system has insufficient memory.
231 functions will fail if:
232 .Bl -tag -width thrd_timedout
234 The system time has reached or exceeded the time specified in
236 before the operation could be completed.
241 function will fail if:
242 .Bl -tag -width thrd_timedout
244 The mutex is already locked.
247 In all other cases, these functions may fail by returning general error
254 These functions are expected to conform to
257 These functions appeared in
260 .An Ed Schouten Aq ed@FreeBSD.org