lib/libthr/libthr.3

   1 .\" Copyright (c) 2005 Robert N. M. Watson
   2 .\" Copyright (c) 2014,2015 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 February 12, 2015
  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.
  51 .Pp
  52 The library is tightly integrated with the run-time link editor
  53 .Xr ld-elf.so.1 1
  54 and
  55 .Lb libc ;
  56 all three components must be built from the same source tree.
  57 Mixing
  58 .Li libc
  59 and
  60 .Nm
  61 libraries from different versions of
  62 .Fx
  63 is not supported.
  64 The run-time linker
  65 .Xr ld-elf.so.1 1
  66 has some code to ensure backward-compatibility with older versions of
  67 .Nm .
  68 .Pp
  69 The man page documents the quirks and tunables of the
  70 .Nm .
  71 When linking with
  72 .Li -lpthread ,
  73 the run-time dependency
  74 .Li libthr.so.3
  75 is recorded in the produced object.
  76 .Sh MUTEX ACQUISITION
  77 A locked mutex (see
  78 .Xr pthread_mutex_lock 3 )
  79 is represented by a volatile variable of type
  80 .Dv lwpid_t ,
  81 which records the global system identifier of the thread
  82 owning the lock.
  83 .Nm
  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
  88 type and
  89 .Dv PTHREAD_PRIO_NONE
  90 protocol (see
  91 .Xr pthread_mutexattr 3 ) .
  92 .Pp
  93 First, on SMP systems, a spin loop
  94 is performed, where the library attempts to acquire the lock by
  95 .Xr atomic 9
  96 operations.
  97 The loop count is controlled by the
  98 .Ev LIBPTHREAD_SPINLOOPS
  99 environment variable, with a default value of 2000.
 100 .Pp
 101 If the spin loop
 102 was unable to acquire the mutex, a yield loop
 103 is executed, performing the same
 104 .Xr atomic 9
 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
 108 .Xr sched_yield 2
 109 syscall.
 110 By default, the yield loop
 111 is not executed.
 112 This is controlled by the
 113 .Ev LIBPTHREAD_YIELDLOOPS
 114 environment variable.
 115 .Pp
 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
 119 .Xr umtx 2
 120 syscall.
 121 The kernel wakes up a thread and hands the ownership of the lock to
 122 the woken thread when the lock becomes available.
 123 .Sh THREAD STACKS
 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
 127 controlled by the
 128 .Dv RLIMIT_STACK
 129 process resource limit (see
 130 .Xr getrlimit 2 ) .
 131 .Pp
 132 By default, the main thread's stack size is equal to the value of
 133 .Dv RLIMIT_STACK
 134 for the process.
 135 If the
 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
 143 in this case.
 144 The presence of the
 145 .Ev LIBPTHREAD_BIGSTACK_MAIN
 146 environment variable overrides
 147 .Ev LIBPTHREAD_SPLITSTACK_MAIN ;
 148 it is kept for backward-compatibility.
 149 .Pp
 150 The size of stacks for threads created by the process at run-time
 151 with the
 152 .Xr pthread_create 3
 153 call is controlled by thread attributes: see
 154 .Xr pthread_attr 3 ,
 155 in particular, the
 156 .Xr pthread_attr_setstacksize 3 ,
 157 .Xr pthread_attr_setguardsize 3
 158 and
 159 .Xr pthread_attr_setstackaddr 3
 160 functions.
 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
 166 .Nm
 167 and adjust the operation of the library at run-time:
 168 .Bl -tag -width 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
 174 section
 175 .Sx THREAD STACKS .
 176 This was the default behaviour of
 177 .Nm
 178 before
 179 .Fx 11.0 .
 180 .It Ev LIBPTHREAD_SPINLOOPS
 181 The integer value of the variable overrides the default count of
 182 iterations in the
 183 .Li spin loop
 184 of the mutex acquisition.
 185 The default count is 2000, set by the
 186 .Dv MUTEX_ADAPTIVE_SPINS
 187 constant in the
 188 .Nm
 189 sources.
 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.
 199 .El
 200 .Sh INTERACTION WITH RUN-TIME LINKER
 201 On load,
 202 .Nm
 203 installs interposing handlers into the hooks exported by
 204 .Li libc .
 205 The interposers provide real locking implementation instead of the
 206 stubs for single-threaded processes in
 207 .Li ,
 208 cancellation support and some modifications to the signal operations.
 209 .Pp
 210 .Nm
 211 cannot be unloaded; the
 212 .Xr dlclose 3
 213 function does not perform any action when called with a handle for
 214 .Nm .
 215 One of the reasons is that the internal interposing of
 216 .Li libc
 217 functions cannot be undone.
 218 .Sh SIGNALS
 219 The implementation interposes the user-installed
 220 .Xr signal 3
 221 handlers.
 222 This interposing is done to postpone signal delivery to threads which
 223 entered (libthr-internal) critical sections, where the calling
 224 of the user-provided signal handler is unsafe.
 225 An example of such a situation is owning the internal library lock.
 226 When a signal is delivered while the signal handler cannot be safely
 227 called, the call is postponed and performed until after the exit from
 228 the critical section.
 229 This should be taken into account when interpreting
 230 .Xr ktrace 1
 231 logs.
 232 .Sh SEE ALSO
 233 .Xr ktrace 1 ,
 234 .Xr ld-elf.so.1 1 ,
 235 .Xr getrlimit 2 ,
 236 .Xr umtx 2 ,
 237 .Xr dlclose 3 ,
 238 .Xr dlopen 3 ,
 239 .Xr errno 3 ,
 240 .Xr getenv 3 ,
 241 .Xr libc 3 ,
 242 .Xr pthread_attr 3 ,
 243 .Xr pthread_attr_setstacksize 3 ,
 244 .Xr pthread_create 3 ,
 245 .Xr signal 3 ,
 246 .Xr atomic 9
 247 .Sh AUTHORS
 248 .An -nosplit
 249 The
 250 .Nm
 251 library
 252 was originally created by
 253 .An "Jeff Roberson" Aq jeff@FreeBSD.org ,
 254 and enhanced by
 255 .An "Jonathan Mini" Aq mini@FreeBSD.org
 256 and
 257 .An "Mike Makonnen" Aq mtm@FreeBSD.org .
 258 It has been substantially rewritten and optimized by
 259 .An "David Xu" Aq davidxu@FreeBSD.org .