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