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
54 .Nd C11 threads interface
60 .Fn call_once "once_flag *flag" "void (*func)(void)"
62 .Fn cnd_broadcast "cnd_t *cond"
64 .Fn cnd_destroy "cnd_t *cond"
66 .Fn cnd_init "cnd_t *cond"
68 .Fn cnd_signal "cnd_t *cond"
70 .Fn cnd_timedwait "cnd_t * restrict cond" "mtx_t * restrict mtx" "const struct timespec * restrict ts"
72 .Fn cnd_wait "cnd_t *cond" "mtx_t *mtx"
74 .Fn mtx_destroy "mtx_t *mtx"
76 .Fn mtx_init "mtx_t *mtx" "int type"
78 .Fn mtx_lock "mtx_t *mtx"
80 .Fn mtx_timedlock "mtx_t * restrict mtx" "const struct timespec * restrict ts"
82 .Fn mtx_trylock "mtx_t *mtx"
84 .Fn mtx_unlock "mtx_t *mtx"
86 .Fn thrd_create "thrd_t *thr" "int (*func)(void *)" "void *arg"
88 .Fn thrd_current "void"
90 .Fn thrd_detach "thrd_t thr"
92 .Fn thrd_equal "thrd_t thr0" "thrd_t thr1"
94 .Fn thrd_exit "int res"
96 .Fn thrd_join "thrd_t thr" "int *res"
98 .Fn thrd_sleep "const struct timespec *duration" "struct timespec *remaining"
100 .Fn thrd_yield "void"
102 .Fn tss_create "tss_t *key" "void (*dtor)(void *)"
104 .Fn tss_delete "tss_t key"
106 .Fn tss_get "tss_t key"
108 .Fn tss_set "tss_t key" "void *val"
112 the C standard includes an API for writing multithreaded applications.
113 Since POSIX.1 already includes a threading API that is used by virtually
114 any multithreaded application, the interface provided by the C standard
115 can be considered superfluous.
117 In this implementation, the threading interface is therefore implemented
118 as a light-weight layer on top of existing interfaces.
119 The functions to which these routines are mapped, are listed in the
121 Please refer to the documentation of the POSIX equivalent functions for
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
151 .Sh DIFFERENCES WITH POSIX EQUIVALENTS
154 function returns an integer value to the thread calling
158 function uses a pointer.
167 to distinguish between a mutex that supports
173 to create a mutex that allows recursive acquisition.
174 These properties are normally set using
175 .Fn pthread_mutex_init Ns 's
200 Otherwise an error code will be returned to indicate the error.
204 function returns the thread ID of the calling thread.
208 function returns the thread-specific data value associated with the
211 If no thread-specific data value is associated with
213 then the value NULL is returned.
219 functions will fail if:
220 .Bl -tag -width thrd_timedout
222 The system has insufficient memory.
229 functions will fail if:
230 .Bl -tag -width thrd_timedout
232 The system time has reached or exceeded the time specified in
234 before the operation could be completed.
239 function will fail if:
240 .Bl -tag -width thrd_timedout
242 The mutex is already locked.
245 In all other cases, these functions may fail by returning general error
252 These functions are expected to conform to
255 These functions appeared in
258 .An Ed Schouten Aq Mt ed@FreeBSD.org