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