1.\" Copyright (c) 2005 Robert N. M. Watson 2.\" Copyright (c) 2014 The FreeBSD Foundation, Inc. 3.\" All rights reserved. 4.\" 5.\" Part of this documentation was written by 6.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship 7.\" from the FreeBSD Foundation. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 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. 17.\" 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 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd September 26, 2014 33.Dt LIBTHR 3 34.Os 35.Sh NAME 36.Nm libthr 37.Nd "1:1 POSIX threads library" 38.Sh LIBRARY 39.Lb libthr 40.Sh SYNOPSIS 41.In pthread.h 42.Sh DESCRIPTION 43The 44.Nm 45library provides a 1:1 implementation of the 46.Xr pthread 3 47library interfaces for application threading. 48It 49has been optimized for use by applications expecting system scope thread 50semantics, and can provide significant performance improvements 51compared to 52.Lb libkse . 53.Pp 54The library is tightly integrated with the run-time link editor 55.Xr ld-elf.so.1 1 56and 57.Lb libc ; 58all three components must be built from the same source tree. 59Mixing 60.Li libc 61and 62.Nm 63libraries from different versions of 64.Fx 65is not supported. 66The run-time linker 67.Xr ld-elf.so.1 1 68has some code to ensure backward-compatibility with older versions of 69.Nm . 70.Pp 71The man page documents the quirks and tunables of the 72.Nm . 73When linking with 74.Li -lpthread , 75the run-time dependency 76.Li libthr.so.3 77is recorded in the produced object. 78.Sh MUTEX ACQUISITION 79A locked mutex (see 80.Xr pthread_mutex_lock 3 ) 81is represented by a volatile variable of type 82.Dv lwpid_t , 83which records the global system identifier of the thread 84owning the lock. 85.Nm 86performs a contested mutex acquisition in three stages, each of which 87is more resource-consuming than the previous. 88The first two stages are only applied for a mutex of 89.Dv PTHREAD_MUTEX_ADAPTIVE_NP 90type and 91.Dv PTHREAD_PRIO_NONE 92protocol (see 93.Xr pthread_mutexattr 3 ) . 94.Pp 95First, on SMP systems, a spin loop 96is performed, where the library attempts to acquire the lock by 97.Xr atomic 9 98operations. 99The loop count is controlled by the 100.Ev LIBPTHREAD_SPINLOOPS 101environment variable, with a default value of 2000. 102.Pp 103If the spin loop 104was unable to acquire the mutex, a yield loop 105is executed, performing the same 106.Xr atomic 9 107acquisition attempts as the spin loop, 108but each attempt is followed by a yield of the CPU time 109of the thread using the 110.Xr sched_yield 2 111syscall. 112By default, the yield loop 113is not executed. 114This is controlled by the 115.Ev LIBPTHREAD_YIELDLOOPS 116environment variable. 117.Pp 118If both the spin and yield loops 119failed to acquire the lock, the thread is taken off the CPU and 120put to sleep in the kernel with the 121.Xr umtx 2 122syscall. 123The kernel wakes up a thread and hands the ownership of the lock to 124the woken thread when the lock becomes available. 125.Sh THREAD STACKS 126Each thread is provided with a private user-mode stack area 127used by the C runtime. 128The size of the main (initial) thread stack is set by the kernel, and is 129controlled by the 130.Dv RLIMIT_STACK 131process resource limit (see 132.Xr getrlimit 2 ) . 133.Pp 134By default, the main thread's stack size is equal to the value of 135.Dv RLIMIT_STACK 136for the process. 137If the 138.Ev LIBPTHREAD_SPLITSTACK_MAIN 139environment variable is present in the process environment 140(its value does not matter), 141the main thread's stack is reduced to 4MB on 64bit architectures, and to 1422MB on 32bit architectures, when the threading library is initialized. 143The rest of the address space area which has been reserved by the 144kernel for the initial process stack is used for non-initial thread stacks 145in this case. 146The presence of the 147.Ev LIBPTHREAD_BIGSTACK_MAIN 148environment variable overrides 149.Ev LIBPTHREAD_SPLITSTACK_MAIN ; 150it is kept for backward-compatibility. 151.Pp 152The size of stacks for threads created by the process at run-time 153with the 154.Xr pthread_create 3 155call is controlled by thread attributes: see 156.Xr pthread_attr 3 , 157in particular, the 158.Xr pthread_attr_setstacksize 3 , 159.Xr pthread_attr_setguardsize 3 160and 161.Xr pthread_attr_setstackaddr 3 162functions. 163If no attributes for the thread stack size are specified, the default 164non-initial thread stack size is 2MB for 64bit architectures, and 1MB 165for 32bit architectures. 166.Sh RUN-TIME SETTINGS 167The following environment variables are recognized by 168.Nm 169and adjust the operation of the library at run-time: 170.Bl -tag -width LIBPTHREAD_SPLITSTACK_MAIN 171.It Ev LIBPTHREAD_BIGSTACK_MAIN 172Disables the reduction of the initial thread stack enabled by 173.Ev LIBPTHREAD_SPLITSTACK_MAIN . 174.It Ev LIBPTHREAD_SPLITSTACK_MAIN 175Causes a reduction of the initial thread stack, as described in the 176section 177.Sx THREAD STACKS . 178This was the default behaviour of 179.Nm 180before 181.Fx 11.0 . 182.It Ev LIBPTHREAD_SPINLOOPS 183The integer value of the variable overrides the default count of 184iterations in the 185.Li spin loop 186of the mutex acquisition. 187The default count is 2000, set by the 188.Dv MUTEX_ADAPTIVE_SPINS 189constant in the 190.Nm 191sources. 192.It Ev LIBPTHREAD_YIELDLOOPS 193A non-zero integer value enables the yield loop 194in the process of the mutex acquisition. 195The value is the count of loop operations. 196.It Ev LIBPTHREAD_QUEUE_FIFO 197The integer value of the variable specifies how often blocked 198threads are inserted at the head of the sleep queue, instead of its tail. 199Bigger values reduce the frequency of the FIFO discipline. 200The value must be between 0 and 255. 201.El 202.Sh INTERACTION WITH RUN-TIME LINKER 203The 204.Nm 205library must appear before 206.Li libc 207in the global order of depended objects. 208.Pp 209Loading 210.Nm 211with the 212.Xr dlopen 3 213call in the process after the program binary is activated 214is not supported, and causes miscellaneous and hard-to-diagnose misbehaviour. 215This is due to 216.Nm 217interposing several important 218.Li libc 219symbols to provide thread-safe services. 220In particular, 221.Dv errno 222and the locking stubs from 223.Li libc 224are affected. 225This requirement is currently not enforced. 226.Pp 227If the program loads any modules at run-time, and those modules may require 228threading services, the main program binary must be linked with 229.Li libpthread , 230even if it does not require any services from the library. 231.Pp 232.Nm 233cannot be unloaded; the 234.Xr dlclose 3 235function does not perform any action when called with a handle for 236.Nm . 237One of the reasons is that the interposing of 238.Li libc 239functions cannot be undone. 240.Sh SIGNALS 241The implementation also interposes the user-installed 242.Xr signal 3 243handlers. 244This interposing is done to postpone signal delivery to threads which 245entered (libthr-internal) critical sections, where the calling 246of the user-provided signal handler is unsafe. 247An example of such a situation is owning the internal library lock. 248When a signal is delivered while the signal handler cannot be safely 249called, the call is postponed and performed until after the exit from 250the critical section. 251This should be taken into account when interpreting 252.Xr ktrace 1 253logs. 254.Sh SEE ALSO 255.Xr ktrace 1 , 256.Xr ld-elf.so.1 1 , 257.Xr getrlimit 2 , 258.Xr umtx 2 , 259.Xr dlclose 3 , 260.Xr dlopen 3 , 261.Xr errno 3 , 262.Xr getenv 3 , 263.Xr libc 3 , 264.Xr pthread_attr 3 , 265.Xr pthread_attr_setstacksize 3 , 266.Xr pthread_create 3 , 267.Xr signal 3 , 268.Xr atomic 9 269.Sh AUTHORS 270.An -nosplit 271The 272.Nm 273library 274was originally created by 275.An Jeff Roberson Aq Mt jeff@FreeBSD.org , 276and enhanced by 277.An Jonathan Mini Aq Mt mini@FreeBSD.org 278and 279.An Mike Makonnen Aq Mt mtm@FreeBSD.org . 280It has been substantially rewritten and optimized by 281.An David Xu Aq Mt davidxu@FreeBSD.org . 282