doc/manual/threading.texinfo

   1 @node  Threading
   2 @comment  node-name,  next,  previous,  up
   3 @chapter Threading
   4
   5 SBCL supports a fairly low-level threading interface that maps onto
   6 the host operating system's concept of threads or lightweight
   7 processes.  This means that threads may take advantage of hardware
   8 multiprocessing on machines that have more than one CPU, but it does
   9 not allow Lisp control of the scheduler.  This is found in the
  10 SB-THREAD package.
  11
  12 Threads are part of the default build on x86[-64] Linux only.
  13
  14 They are also experimentally supported on: x86[-64] Darwin (Mac OS X),
  15 x86[-64] FreeBSD, and x86 SunOS (Solaris). On these platforms threads
  16 must be explicitly enabled at build-time, see @file{INSTALL} for
  17 directions.
  18
  19 @menu
  20 * Threading basics::
  21 * Special Variables::
  22 * Mutex Support::
  23 * Semaphores::
  24 * Waitqueue/condition variables::
  25 * Sessions/Debugging::
  26 * Foreign threads::
  27 * Implementation (Linux x86/x86-64)::
  28 @end menu
  29
  30 @node Threading basics
  31 @comment  node-name,  next,  previous,  up
  32 @section Threading basics
  33
  34 @lisp
  35 (make-thread (lambda () (write-line "Hello, world")))
  36 @end lisp
  37
  38 @subsection Thread Objects
  39
  40 @include struct-sb-thread-thread.texinfo
  41 @include var-sb-thread-star-current-thread-star.texinfo
  42 @include fun-sb-thread-list-all-threads.texinfo
  43 @include fun-sb-thread-thread-alive-p.texinfo
  44 @include fun-sb-thread-thread-name.texinfo
  45
  46 @subsection Making, Joining, and Yielding Threads
  47
  48 @include fun-sb-thread-make-thread.texinfo
  49 @include fun-sb-thread-thread-yield.texinfo
  50 @include fun-sb-thread-join-thread.texinfo
  51
  52 @subsection Asynchronous Operations
  53
  54 @include fun-sb-thread-interrupt-thread.texinfo
  55 @include fun-sb-thread-terminate-thread.texinfo
  56
  57 @subsection Miscellaneous Operations
  58
  59 @include fun-sb-thread-symbol-value-in-thread.texinfo
  60
  61 @subsection Error Conditions
  62
  63 @include condition-sb-thread-thread-error.texinfo
  64 @include fun-sb-thread-thread-error-thread.texinfo
  65
  66 @c @include condition-sb-thread-symbol-value-in-thread-error.texinfo
  67 @include condition-sb-thread-interrupt-thread-error.texinfo
  68 @include condition-sb-thread-join-thread-error.texinfo
  69
  70 @node Special Variables
  71 @comment  node-name,  next,  previous,  up
  72 @section Special Variables
  73
  74 The interaction of special variables with multiple threads is mostly
  75 as one would expect, with behaviour very similar to other
  76 implementations.
  77
  78 @itemize
  79 @item
  80 global special values are visible across all threads;
  81 @item
  82 bindings (e.g. using LET) are local to the thread;
  83 @item
  84 threads do not inherit dynamic bindings from the parent thread
  85 @end itemize
  86
  87 The last point means that
  88
  89 @lisp
  90 (defparameter *x* 0)
  91 (let ((*x* 1))
  92   (sb-thread:make-thread (lambda () (print *x*))))
  93 @end lisp
  94
  95 prints @code{0} and not @code{1} as of 0.9.6.
  96
  97 @node Mutex Support
  98 @comment  node-name,  next,  previous,  up
  99 @section Mutex Support
 100
 101 Mutexes are used for controlling access to a shared resource. One
 102 thread is allowed to hold the mutex, others which attempt to take it
 103 will be made to wait until it's free. Threads are woken in the order
 104 that they go to sleep.
 105
 106 There isn't a timeout on mutex acquisition, but the usual WITH-TIMEOUT
 107 macro (which throws a TIMEOUT condition after n seconds) can be used
 108 if you want a bounded wait.
 109
 110 @lisp
 111 (defpackage :demo (:use "CL" "SB-THREAD" "SB-EXT"))
 112
 113 (in-package :demo)
 114
 115 (defvar *a-mutex* (make-mutex :name "my lock"))
 116
 117 (defun thread-fn ()
 118   (format t "Thread ~A running ~%" *current-thread*)
 119   (with-mutex (*a-mutex*)
 120     (format t "Thread ~A got the lock~%" *current-thread*)
 121     (sleep (random 5)))
 122   (format t "Thread ~A dropped lock, dying now~%" *current-thread*))
 123
 124 (make-thread #'thread-fn)
 125 (make-thread #'thread-fn)
 126 @end lisp
 127
 128 @include struct-sb-thread-mutex.texinfo
 129 @include fun-sb-thread-make-mutex.texinfo
 130 @include fun-sb-thread-mutex-name.texinfo
 131 @include fun-sb-thread-mutex-value.texinfo
 132 @include fun-sb-thread-get-mutex.texinfo
 133 @include fun-sb-thread-release-mutex.texinfo
 134 @include macro-sb-thread-with-mutex.texinfo
 135 @include macro-sb-thread-with-recursive-lock.texinfo
 136
 137 @node Semaphores
 138 @comment  node-name,  next,  previous,  up
 139 @section Semaphores
 140
 141 described here should be considered
 142 experimental, subject to API changes without notice.
 143
 144 @include struct-sb-thread-semaphore.texinfo
 145 @include fun-sb-thread-make-semaphore.texinfo
 146 @include fun-sb-thread-semaphore-count.texinfo
 147 @include fun-sb-thread-semaphore-name.texinfo
 148 @include fun-sb-thread-signal-semaphore.texinfo
 149 @include fun-sb-thread-wait-on-semaphore.texinfo
 150
 151 @node Waitqueue/condition variables
 152 @comment  node-name,  next,  previous,  up
 153 @section Waitqueue/condition variables
 154
 155 These are based on the POSIX condition variable design, hence the
 156 annoyingly CL-conflicting name. For use when you want to check a
 157 condition and sleep until it's true. For example: you have a shared
 158 queue, a writer process checking ``queue is empty'' and one or more
 159 readers that need to know when ``queue is not empty''. It sounds
 160 simple, but is astonishingly easy to deadlock if another process runs
 161 when you weren't expecting it to.
 162
 163 There are three components:
 164
 165 @itemize
 166 @item
 167 the condition itself (not represented in code)
 168
 169 @item
 170 the condition variable (a.k.a waitqueue) which proxies for it
 171
 172 @item
 173 a lock to hold while testing the condition
 174 @end itemize
 175
 176 Important stuff to be aware of:
 177
 178 @itemize
 179 @item
 180 when calling condition-wait, you must hold the mutex. condition-wait
 181 will drop the mutex while it waits, and obtain it again before
 182 returning for whatever reason;
 183
 184 @item
 185 likewise, you must be holding the mutex around calls to
 186 condition-notify;
 187
 188 @item
 189 a process may return from condition-wait in several circumstances: it
 190 is not guaranteed that the underlying condition has become true. You
 191 must check that the resource is ready for whatever you want to do to
 192 it.
 193
 194 @end itemize
 195
 196 @lisp
 197 (defvar *buffer-queue* (make-waitqueue))
 198 (defvar *buffer-lock* (make-mutex :name "buffer lock"))
 199
 200 (defvar *buffer* (list nil))
 201
 202 (defun reader ()
 203   (with-mutex (*buffer-lock*)
 204     (loop
 205      (condition-wait *buffer-queue* *buffer-lock*)
 206      (loop
 207       (unless *buffer* (return))
 208       (let ((head (car *buffer*)))
 209         (setf *buffer* (cdr *buffer*))
 210         (format t "reader ~A woke, read ~A~%"
 211                 *current-thread* head))))))
 212
 213 (defun writer ()
 214   (loop
 215    (sleep (random 5))
 216    (with-mutex (*buffer-lock*)
 217      (let ((el (intern
 218                 (string (code-char
 219                          (+ (char-code #\A) (random 26)))))))
 220        (setf *buffer* (cons el *buffer*)))
 221      (condition-notify *buffer-queue*))))
 222
 223 (make-thread #'writer)
 224 (make-thread #'reader)
 225 (make-thread #'reader)
 226 @end lisp
 227
 228 @include struct-sb-thread-waitqueue.texinfo
 229 @include fun-sb-thread-make-waitqueue.texinfo
 230 @include fun-sb-thread-waitqueue-name.texinfo
 231 @include fun-sb-thread-condition-wait.texinfo
 232 @include fun-sb-thread-condition-notify.texinfo
 233 @include fun-sb-thread-condition-broadcast.texinfo
 234
 235 @node Sessions/Debugging
 236 @comment  node-name,  next,  previous,  up
 237 @section Sessions/Debugging
 238
 239 If the user has multiple views onto the same Lisp image (for example,
 240 using multiple terminals, or a windowing system, or network access)
 241 they are typically set up as multiple @dfn{sessions} such that each
 242 view has its own collection of foreground/background/stopped threads.
 243 A thread which wishes to create a new session can use
 244 @code{sb-thread:with-new-session} to remove itself from the current
 245 session (which it shares with its parent and siblings) and create a
 246 fresh one.
 247 # See also @code{sb-thread:make-listener-thread}.
 248
 249 Within a single session, threads arbitrate between themselves for the
 250 user's attention.  A thread may be in one of three notional states:
 251 foreground, background, or stopped.  When a background process
 252 attempts to print a repl prompt or to enter the debugger, it will stop
 253 and print a message saying that it has stopped.  The user at his
 254 leisure may switch to that thread to find out what it needs.  If a
 255 background thread enters the debugger, selecting any restart will put
 256 it back into the background before it resumes.  Arbitration for the
 257 input stream is managed by calls to @code{sb-thread:get-foreground}
 258 (which may block) and @code{sb-thread:release-foreground}.
 259
 260 @code{sb-ext:quit} terminates all threads in the current session, but
 261 leaves other sessions running.
 262
 263 @node Foreign threads
 264 @comment  node-name,  next,  previous,  up
 265 @section Foreign threads
 266
 267 Direct calls to @code{pthread_create} (instead of @code{MAKE-THREAD})
 268 create threads that SBCL is not aware of, these are called foreign
 269 threads. Currently, it is not possible to run Lisp code in such
 270 threads. This means that the Lisp side signal handlers cannot work.
 271 The best solution is to start foreign threads with signals blocked,
 272 but since third party libraries may create threads, it is not always
 273 feasible to do so. As a workaround, upon receiving a signal in a
 274 foreign thread, SBCL changes the thread's sigmask to block all signals
 275 that it wants to handle and resends the signal to the current process
 276 which should land in a thread that does not block it, that is, a Lisp
 277 thread.
 278
 279 The resignalling trick cannot work for synchronously triggered signals
 280 (SIGSEGV and co), take care not to trigger any. Resignalling for
 281 synchronously triggered signals in foreign threads is subject to
 282 @code{--lose-on-corruption}, see @ref{Runtime Options}.
 283
 284 @node Implementation (Linux x86/x86-64)
 285 @comment  node-name,  next,  previous,  up
 286 @section Implementation (Linux x86/x86-64)
 287
 288 Threading is implemented using pthreads and some Linux specific bits
 289 like futexes.
 290
 291 On x86 the per-thread local bindings for special variables is achieved
 292 using the %fs segment register to point to a per-thread storage area.
 293 This may cause interesting results if you link to foreign code that
 294 expects threading or creates new threads, and the thread library in
 295 question uses %fs in an incompatible way. On x86-64 the r12 register
 296 has a similar role.
 297
 298 Queues require the @code{sys_futex()} system call to be available:
 299 this is the reason for the NPTL requirement.  We test at runtime that
 300 this system call exists.
 301
 302 Garbage collection is done with the existing Conservative Generational
 303 GC.  Allocation is done in small (typically 8k) regions: each thread
 304 has its own region so this involves no stopping. However, when a
 305 region fills, a lock must be obtained while another is allocated, and
 306 when a collection is required, all processes are stopped.  This is
 307 achieved by sending them signals, which may make for interesting
 308 behaviour if they are interrupted in system calls.  The streams
 309 interface is believed to handle the required system call restarting
 310 correctly, but this may be a consideration when making other blocking
 311 calls e.g. from foreign library code.
 312
 313 Large amounts of the SBCL library have not been inspected for
 314 thread-safety.  Some of the obviously unsafe areas have large locks
 315 around them, so compilation and fasl loading, for example, cannot be
 316 parallelized.  Work is ongoing in this area.
 317
 318 A new thread by default is created in the same POSIX process group and
 319 session as the thread it was created by.  This has an impact on
 320 keyboard interrupt handling: pressing your terminal's intr key
 321 (typically @kbd{Control-C}) will interrupt all processes in the
 322 foreground process group, including Lisp threads that SBCL considers
 323 to be notionally `background'.  This is undesirable, so background
 324 threads are set to ignore the SIGINT signal.
 325
 326 @code{sb-thread:make-listener-thread} in addition to creating a new
 327 Lisp session makes a new POSIX session, so that pressing
 328 @kbd{Control-C} in one window will not interrupt another listener -
 329 this has been found to be embarrassing.