1 .\" Copyright (c) 2005 Robert N. M. Watson
2 .\" Copyright (c) 2014,2015 The FreeBSD Foundation, Inc.
3 .\" All rights reserved.
5 .\" Part of this documentation was written by
6 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
7 .\" from the FreeBSD Foundation.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
37 .Nd "1:1 POSIX threads library"
45 library provides a 1:1 implementation of the
47 library interfaces for application threading.
49 has been optimized for use by applications expecting system scope thread
52 The library is tightly integrated with the run-time link editor
56 all three components must be built from the same source tree.
61 libraries from different versions of
66 has some code to ensure backward-compatibility with older versions of
69 The man page documents the quirks and tunables of the
73 the run-time dependency
75 is recorded in the produced object.
78 .Xr pthread_mutex_lock 3 )
79 is represented by a volatile variable of type
81 which records the global system identifier of the thread
84 performs a contested mutex acquisition in three stages, each of which
85 is more resource-consuming than the previous.
86 The first two stages are only applied for a mutex of
87 .Dv PTHREAD_MUTEX_ADAPTIVE_NP
91 .Xr pthread_mutexattr 3 ) .
93 First, on SMP systems, a spin loop
94 is performed, where the library attempts to acquire the lock by
97 The loop count is controlled by the
98 .Ev LIBPTHREAD_SPINLOOPS
99 environment variable, with a default value of 2000.
102 was unable to acquire the mutex, a yield loop
103 is executed, performing the same
105 acquisition attempts as the spin loop,
106 but each attempt is followed by a yield of the CPU time
107 of the thread using the
110 By default, the yield loop
112 This is controlled by the
113 .Ev LIBPTHREAD_YIELDLOOPS
114 environment variable.
116 If both the spin and yield loops
117 failed to acquire the lock, the thread is taken off the CPU and
118 put to sleep in the kernel with the
121 The kernel wakes up a thread and hands the ownership of the lock to
122 the woken thread when the lock becomes available.
124 Each thread is provided with a private user-mode stack area
125 used by the C runtime.
126 The size of the main (initial) thread stack is set by the kernel, and is
129 process resource limit (see
132 By default, the main thread's stack size is equal to the value of
136 .Ev LIBPTHREAD_SPLITSTACK_MAIN
137 environment variable is present in the process environment
138 (its value does not matter),
139 the main thread's stack is reduced to 4MB on 64bit architectures, and to
140 2MB on 32bit architectures, when the threading library is initialized.
141 The rest of the address space area which has been reserved by the
142 kernel for the initial process stack is used for non-initial thread stacks
145 .Ev LIBPTHREAD_BIGSTACK_MAIN
146 environment variable overrides
147 .Ev LIBPTHREAD_SPLITSTACK_MAIN ;
148 it is kept for backward-compatibility.
150 The size of stacks for threads created by the process at run-time
153 call is controlled by thread attributes: see
156 .Xr pthread_attr_setstacksize 3 ,
157 .Xr pthread_attr_setguardsize 3
159 .Xr pthread_attr_setstackaddr 3
161 If no attributes for the thread stack size are specified, the default
162 non-initial thread stack size is 2MB for 64bit architectures, and 1MB
163 for 32bit architectures.
164 .Sh RUN-TIME SETTINGS
165 The following environment variables are recognized by
167 and adjust the operation of the library at run-time:
168 .Bl -tag -width "Ev LIBPTHREAD_SPLITSTACK_MAIN"
169 .It Ev LIBPTHREAD_BIGSTACK_MAIN
170 Disables the reduction of the initial thread stack enabled by
171 .Ev LIBPTHREAD_SPLITSTACK_MAIN .
172 .It Ev LIBPTHREAD_SPLITSTACK_MAIN
173 Causes a reduction of the initial thread stack, as described in the
176 This was the default behaviour of
180 .It Ev LIBPTHREAD_SPINLOOPS
181 The integer value of the variable overrides the default count of
184 of the mutex acquisition.
185 The default count is 2000, set by the
186 .Dv MUTEX_ADAPTIVE_SPINS
190 .It Ev LIBPTHREAD_YIELDLOOPS
191 A non-zero integer value enables the yield loop
192 in the process of the mutex acquisition.
193 The value is the count of loop operations.
194 .It Ev LIBPTHREAD_QUEUE_FIFO
195 The integer value of the variable specifies how often blocked
196 threads are inserted at the head of the sleep queue, instead of its tail.
197 Bigger values reduce the frequency of the FIFO discipline.
198 The value must be between 0 and 255.
203 MIBs affect the operation of the library:
204 .Bl -tag -width "Dv debug.umtx.robust_faults_verbose"
205 .It Dv kern.ipc.umtx_vnode_persistent
206 By default, a shared lock backed by a mapped file in memory is
207 automatically destroyed on the last unmap of the corresponding file's page,
208 which is allowed by POSIX.
209 Setting the sysctl to 1 makes such a shared lock object persist until
210 the vnode is recycled by the Virtual File System.
211 Note that in case file is not opened and not mapped, the kernel might
212 recycle it at any moment, making this sysctl less useful than it sounds.
213 .It Dv kern.ipc.umtx_max_robust
214 The maximal number of robust mutexes allowed for one thread.
215 The kernel will not unlock more mutexes than specified, see
218 The default value is large enough for most useful applications.
219 .It Dv debug.umtx.robust_faults_verbose
220 A non zero value makes kernel emit some diagnostic when the robust
221 mutexes unlock was prematurely aborted after detecting some inconsistency,
222 as a measure to prevent memory corruption.
229 defines how many shared locks a given user may create simultaneously.
230 .Sh INTERACTION WITH RUN-TIME LINKER
233 installs interposing handlers into the hooks exported by
235 The interposers provide real locking implementation instead of the
236 stubs for single-threaded processes in
238 cancellation support and some modifications to the signal operations.
241 cannot be unloaded; the
243 function does not perform any action when called with a handle for
245 One of the reasons is that the internal interposing of
247 functions cannot be undone.
249 The implementation interposes the user-installed
252 This interposing is done to postpone signal delivery to threads which
253 entered (libthr-internal) critical sections, where the calling
254 of the user-provided signal handler is unsafe.
255 An example of such a situation is owning the internal library lock.
256 When a signal is delivered while the signal handler cannot be safely
257 called, the call is postponed and performed until after the exit from
258 the critical section.
259 This should be taken into account when interpreting
278 .Xr pthread_attr_setstacksize 3 ,
279 .Xr pthread_create 3 ,
287 was originally created by
288 .An Jeff Roberson Aq Mt jeff@FreeBSD.org ,
290 .An Jonathan Mini Aq Mt mini@FreeBSD.org
292 .An Mike Makonnen Aq Mt mtm@FreeBSD.org .
293 It has been substantially rewritten and optimized by
294 .An David Xu Aq Mt davidxu@FreeBSD.org .