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
50 semantics, and can provide significant performance improvements
54 The library is tightly integrated with the run-time link editor
58 all three components must be built from the same source tree.
63 libraries from different versions of
68 has some code to ensure backward-compatibility with older versions of
71 The man page documents the quirks and tunables of the
75 the run-time dependency
77 is recorded in the produced object.
80 .Xr pthread_mutex_lock 3 )
81 is represented by a volatile variable of type
83 which records the global system identifier of the thread
86 performs a contested mutex acquisition in three stages, each of which
87 is more resource-consuming than the previous.
88 The first two stages are only applied for a mutex of
89 .Dv PTHREAD_MUTEX_ADAPTIVE_NP
93 .Xr pthread_mutexattr 3 ) .
95 First, on SMP systems, a spin loop
96 is performed, where the library attempts to acquire the lock by
99 The loop count is controlled by the
100 .Ev LIBPTHREAD_SPINLOOPS
101 environment variable, with a default value of 2000.
104 was unable to acquire the mutex, a yield loop
105 is executed, performing the same
107 acquisition attempts as the spin loop,
108 but each attempt is followed by a yield of the CPU time
109 of the thread using the
112 By default, the yield loop
114 This is controlled by the
115 .Ev LIBPTHREAD_YIELDLOOPS
116 environment variable.
118 If both the spin and yield loops
119 failed to acquire the lock, the thread is taken off the CPU and
120 put to sleep in the kernel with the
123 The kernel wakes up a thread and hands the ownership of the lock to
124 the woken thread when the lock becomes available.
126 Each thread is provided with a private user-mode stack area
127 used by the C runtime.
128 The size of the main (initial) thread stack is set by the kernel, and is
131 process resource limit (see
134 By default, the main thread's stack size is equal to the value of
138 .Ev LIBPTHREAD_SPLITSTACK_MAIN
139 environment variable is present in the process environment
140 (its value does not matter),
141 the main thread's stack is reduced to 4MB on 64bit architectures, and to
142 2MB on 32bit architectures, when the threading library is initialized.
143 The rest of the address space area which has been reserved by the
144 kernel for the initial process stack is used for non-initial thread stacks
147 .Ev LIBPTHREAD_BIGSTACK_MAIN
148 environment variable overrides
149 .Ev LIBPTHREAD_SPLITSTACK_MAIN ;
150 it is kept for backward-compatibility.
152 The size of stacks for threads created by the process at run-time
155 call is controlled by thread attributes: see
158 .Xr pthread_attr_setstacksize 3 ,
159 .Xr pthread_attr_setguardsize 3
161 .Xr pthread_attr_setstackaddr 3
163 If no attributes for the thread stack size are specified, the default
164 non-initial thread stack size is 2MB for 64bit architectures, and 1MB
165 for 32bit architectures.
166 .Sh RUN-TIME SETTINGS
167 The following environment variables are recognized by
169 and adjust the operation of the library at run-time:
170 .Bl -tag -width LIBPTHREAD_SPLITSTACK_MAIN
171 .It Ev LIBPTHREAD_BIGSTACK_MAIN
172 Disables the reduction of the initial thread stack enabled by
173 .Ev LIBPTHREAD_SPLITSTACK_MAIN .
174 .It Ev LIBPTHREAD_SPLITSTACK_MAIN
175 Causes a reduction of the initial thread stack, as described in the
178 This was the default behaviour of
182 .It Ev LIBPTHREAD_SPINLOOPS
183 The integer value of the variable overrides the default count of
186 of the mutex acquisition.
187 The default count is 2000, set by the
188 .Dv MUTEX_ADAPTIVE_SPINS
192 .It Ev LIBPTHREAD_YIELDLOOPS
193 A non-zero integer value enables the yield loop
194 in the process of the mutex acquisition.
195 The value is the count of loop operations.
196 .It Ev LIBPTHREAD_QUEUE_FIFO
197 The integer value of the variable specifies how often blocked
198 threads are inserted at the head of the sleep queue, instead of its tail.
199 Bigger values reduce the frequency of the FIFO discipline.
200 The value must be between 0 and 255.
202 .Sh INTERACTION WITH RUN-TIME LINKER
205 installs interposing handlers into the hooks exported by
207 The interposers provide real locking implementation instead of the
208 stubs for single-threaded processes in
210 cancellation support and some modifications to the signal operations.
213 cannot be unloaded; the
215 function does not perform any action when called with a handle for
217 One of the reasons is that the internal interposing of
219 functions cannot be undone.
221 The implementation interposes the user-installed
224 This interposing is done to postpone signal delivery to threads which
225 entered (libthr-internal) critical sections, where the calling
226 of the user-provided signal handler is unsafe.
227 An example of such a situation is owning the internal library lock.
228 When a signal is delivered while the signal handler cannot be safely
229 called, the call is postponed and performed until after the exit from
230 the critical section.
231 This should be taken into account when interpreting
245 .Xr pthread_attr_setstacksize 3 ,
246 .Xr pthread_create 3 ,
254 was originally created by
255 .An "Jeff Roberson" Aq jeff@FreeBSD.org ,
257 .An "Jonathan Mini" Aq mini@FreeBSD.org
259 .An "Mike Makonnen" Aq mtm@FreeBSD.org .
260 It has been substantially rewritten and optimized by
261 .An "David Xu" Aq davidxu@FreeBSD.org .