lib/libthr/libthr.3

   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
  43 The
  44 .Nm
  45 library provides a 1:1 implementation of the
  46 .Xr pthread 3
  47 library interfaces for application threading.
  48 It
  49 has been optimized for use by applications expecting system scope thread
  50 semantics, and can provide significant performance improvements
  51 compared to
  52 .Lb libkse .
  53 .Pp
  54 The library is tightly integrated with the run-time link editor
  55 .Xr ld-elf.so.1 1
  56 and
  57 .Lb libc ;
  58 all three components must be built from the same source tree.
  59 Mixing
  60 .Li libc
  61 and
  62 .Nm
  63 libraries from different versions of
  64 .Fx
  65 is not supported.
  66 The run-time linker
  67 .Xr ld-elf.so.1 1
  68 has some code to ensure backward-compatibility with older versions of
  69 .Nm .
  70 .Pp
  71 The man page documents the quirks and tunables of the
  72 .Nm .
  73 When linking with
  74 .Li -lpthread ,
  75 the run-time dependency
  76 .Li libthr.so.3
  77 is recorded in the produced object.
  78 .Sh MUTEX ACQUISITION
  79 A locked mutex (see
  80 .Xr pthread_mutex_lock 3 )
  81 is represented by a volatile variable of type
  82 .Dv lwpid_t ,
  83 which records the global system identifier of the thread
  84 owning the lock.
  85 .Nm
  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
  90 type and
  91 .Dv PTHREAD_PRIO_NONE
  92 protocol (see
  93 .Xr pthread_mutexattr 3 ) .
  94 .Pp
  95 First, on SMP systems, a spin loop
  96 is performed, where the library attempts to acquire the lock by
  97 .Xr atomic 9
  98 operations.
  99 The loop count is controlled by the
 100 .Ev LIBPTHREAD_SPINLOOPS
 101 environment variable, with a default value of 2000.
 102 .Pp
 103 If the spin loop
 104 was unable to acquire the mutex, a yield loop
 105 is executed, performing the same
 106 .Xr atomic 9
 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
 110 .Xr sched_yield 2
 111 syscall.
 112 By default, the yield loop
 113 is not executed.
 114 This is controlled by the
 115 .Ev LIBPTHREAD_YIELDLOOPS
 116 environment variable.
 117 .Pp
 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
 121 .Xr umtx 2
 122 syscall.
 123 The kernel wakes up a thread and hands the ownership of the lock to
 124 the woken thread when the lock becomes available.
 125 .Sh THREAD STACKS
 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
 129 controlled by the
 130 .Dv RLIMIT_STACK
 131 process resource limit (see
 132 .Xr getrlimit 2 ) .
 133 .Pp
 134 By default, the main thread's stack size is equal to the value of
 135 .Dv RLIMIT_STACK
 136 for the process.
 137 If the
 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
 145 in this case.
 146 The presence of the
 147 .Ev LIBPTHREAD_BIGSTACK_MAIN
 148 environment variable overrides
 149 .Ev LIBPTHREAD_SPLITSTACK_MAIN ;
 150 it is kept for backward-compatibility.
 151 .Pp
 152 The size of stacks for threads created by the process at run-time
 153 with the
 154 .Xr pthread_create 3
 155 call is controlled by thread attributes: see
 156 .Xr pthread_attr 3 ,
 157 in particular, the
 158 .Xr pthread_attr_setstacksize 3 ,
 159 .Xr pthread_attr_setguardsize 3
 160 and
 161 .Xr pthread_attr_setstackaddr 3
 162 functions.
 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
 168 .Nm
 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
 176 section
 177 .Sx THREAD STACKS .
 178 This was the default behaviour of
 179 .Nm
 180 before
 181 .Fx 11.0 .
 182 .It Ev LIBPTHREAD_SPINLOOPS
 183 The integer value of the variable overrides the default count of
 184 iterations in the
 185 .Li spin loop
 186 of the mutex acquisition.
 187 The default count is 2000, set by the
 188 .Dv MUTEX_ADAPTIVE_SPINS
 189 constant in the
 190 .Nm
 191 sources.
 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.
 201 .El
 202 .Sh INTERACTION WITH RUN-TIME LINKER
 203 The
 204 .Nm
 205 library must appear before
 206 .Li libc
 207 in the global order of depended objects.
 208 .Pp
 209 Loading
 210 .Nm
 211 with the
 212 .Xr dlopen 3
 213 call in the process after the program binary is activated
 214 is not supported, and causes miscellaneous and hard-to-diagnose misbehaviour.
 215 This is due to
 216 .Nm
 217 interposing several important
 218 .Li libc
 219 symbols to provide thread-safe services.
 220 In particular,
 221 .Dv errno
 222 and the locking stubs from
 223 .Li libc
 224 are affected.
 225 This requirement is currently not enforced.
 226 .Pp
 227 If the program loads any modules at run-time, and those modules may require
 228 threading services, the main program binary must be linked with
 229 .Li libpthread ,
 230 even if it does not require any services from the library.
 231 .Pp
 232 .Nm
 233 cannot be unloaded; the
 234 .Xr dlclose 3
 235 function does not perform any action when called with a handle for
 236 .Nm .
 237 One of the reasons is that the interposing of
 238 .Li libc
 239 functions cannot be undone.
 240 .Sh SIGNALS
 241 The implementation also interposes the user-installed
 242 .Xr signal 3
 243 handlers.
 244 This interposing is done to postpone signal delivery to threads which
 245 entered (libthr-internal) critical sections, where the calling
 246 of the user-provided signal handler is unsafe.
 247 An example of such a situation is owning the internal library lock.
 248 When a signal is delivered while the signal handler cannot be safely
 249 called, the call is postponed and performed until after the exit from
 250 the critical section.
 251 This should be taken into account when interpreting
 252 .Xr ktrace 1
 253 logs.
 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
 271 The
 272 .Nm
 273 library
 274 was originally created by
 275 .An "Jeff Roberson" Aq jeff@FreeBSD.org ,
 276 and enhanced by
 277 .An "Jonathan Mini" Aq mini@FreeBSD.org
 278 and
 279 .An "Mike Makonnen" Aq mtm@FreeBSD.org .
 280 It has been substantially rewritten and optimized by
 281 .An "David Xu" Aq davidxu@FreeBSD.org .