2 @comment node-name, next, previous, up
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
12 Threads are part of the default build on x86[-64] Linux only.
14 They are also experimentally supported on: x86[-64] Darwin (Mac OS X),
15 x86[-64] FreeBSD, x86 SunOS (Solaris), and PPC Linux. On these platforms
16 threads must be explicitly enabled at build-time, see @file{INSTALL} for
25 * Waitqueue/condition variables::
27 * Sessions/Debugging::
29 * Implementation (Linux x86/x86-64)::
32 @node Threading basics
33 @comment node-name, next, previous, up
34 @section Threading basics
37 (make-thread (lambda () (write-line "Hello, world")))
40 @subsection Thread Objects
42 @include struct-sb-thread-thread.texinfo
43 @include var-sb-thread-star-current-thread-star.texinfo
44 @include fun-sb-thread-list-all-threads.texinfo
45 @include fun-sb-thread-thread-alive-p.texinfo
46 @include fun-sb-thread-thread-name.texinfo
48 @subsection Making, Joining, and Yielding Threads
50 @include fun-sb-thread-make-thread.texinfo
51 @include fun-sb-thread-thread-yield.texinfo
52 @include fun-sb-thread-join-thread.texinfo
54 @subsection Asynchronous Operations
56 @include fun-sb-thread-interrupt-thread.texinfo
57 @include fun-sb-thread-terminate-thread.texinfo
59 @subsection Miscellaneous Operations
61 @include fun-sb-thread-symbol-value-in-thread.texinfo
63 @subsection Error Conditions
65 @include condition-sb-thread-thread-error.texinfo
66 @include fun-sb-thread-thread-error-thread.texinfo
68 @c @include condition-sb-thread-symbol-value-in-thread-error.texinfo
69 @include condition-sb-thread-interrupt-thread-error.texinfo
70 @include condition-sb-thread-join-thread-error.texinfo
72 @node Special Variables
73 @comment node-name, next, previous, up
74 @section Special Variables
76 The interaction of special variables with multiple threads is mostly
77 as one would expect, with behaviour very similar to other
82 global special values are visible across all threads;
84 bindings (e.g. using LET) are local to the thread;
86 threads do not inherit dynamic bindings from the parent thread
89 The last point means that
94 (sb-thread:make-thread (lambda () (print *x*))))
97 prints @code{0} and not @code{1} as of 0.9.6.
99 @node Atomic Operations
100 @comment node-name, next, previous, up
101 @section Atomic Operations
103 SBCL provides a few special purpose atomic operations, particularly
104 useful for implementing lockless algorithms.
106 @include macro-sb-ext-atomic-decf.texinfo
107 @include macro-sb-ext-atomic-incf.texinfo
108 @include macro-sb-ext-compare-and-swap.texinfo
110 @unnumberedsubsec CAS Protocol
112 Our @code{compare-and-swap} is user-extensible using a protocol similar
115 @include macro-sb-ext-cas.texinfo
116 @include macro-sb-ext-define-cas-expander.texinfo
117 @include macro-sb-ext-defcas.texinfo
118 @include fun-sb-ext-get-cas-expansion.texinfo
121 @comment node-name, next, previous, up
122 @section Mutex Support
124 Mutexes are used for controlling access to a shared resource. One
125 thread is allowed to hold the mutex, others which attempt to take it
126 will be made to wait until it's free. Threads are woken in the order
127 that they go to sleep.
129 There isn't a timeout on mutex acquisition, but the usual WITH-TIMEOUT
130 macro (which throws a TIMEOUT condition after n seconds) can be used
131 if you want a bounded wait.
134 (defpackage :demo (:use "CL" "SB-THREAD" "SB-EXT"))
138 (defvar *a-mutex* (make-mutex :name "my lock"))
141 (format t "Thread ~A running ~%" *current-thread*)
142 (with-mutex (*a-mutex*)
143 (format t "Thread ~A got the lock~%" *current-thread*)
145 (format t "Thread ~A dropped lock, dying now~%" *current-thread*))
147 (make-thread #'thread-fn)
148 (make-thread #'thread-fn)
151 @include struct-sb-thread-mutex.texinfo
152 @include fun-sb-thread-make-mutex.texinfo
153 @include fun-sb-thread-mutex-name.texinfo
154 @include fun-sb-thread-mutex-value.texinfo
155 @include fun-sb-thread-grab-mutex.texinfo
156 @include fun-sb-thread-release-mutex.texinfo
157 @include macro-sb-thread-with-mutex.texinfo
158 @include macro-sb-thread-with-recursive-lock.texinfo
159 @include fun-sb-thread-get-mutex.texinfo
162 @comment node-name, next, previous, up
165 Semaphores are among other things useful for keeping track of a
166 countable resource, eg. messages in a queue, and sleep when the
167 resource is exhausted.
169 @include struct-sb-thread-semaphore.texinfo
170 @include fun-sb-thread-make-semaphore.texinfo
171 @include fun-sb-thread-signal-semaphore.texinfo
172 @include fun-sb-thread-wait-on-semaphore.texinfo
173 @include fun-sb-thread-try-semaphore.texinfo
174 @include fun-sb-thread-semaphore-count.texinfo
175 @include fun-sb-thread-semaphore-name.texinfo
177 @include struct-sb-thread-semaphore-notification.texinfo
178 @include fun-sb-thread-make-semaphore-notification.texinfo
179 @include fun-sb-thread-semaphore-notification-status.texinfo
180 @include fun-sb-thread-clear-semaphore-notification.texinfo
182 @node Waitqueue/condition variables
183 @comment node-name, next, previous, up
184 @section Waitqueue/condition variables
186 These are based on the POSIX condition variable design, hence the
187 annoyingly CL-conflicting name. For use when you want to check a
188 condition and sleep until it's true. For example: you have a shared
189 queue, a writer process checking ``queue is empty'' and one or more
190 readers that need to know when ``queue is not empty''. It sounds
191 simple, but is astonishingly easy to deadlock if another process runs
192 when you weren't expecting it to.
194 There are three components:
198 the condition itself (not represented in code)
201 the condition variable (a.k.a waitqueue) which proxies for it
204 a lock to hold while testing the condition
207 Important stuff to be aware of:
211 when calling condition-wait, you must hold the mutex. condition-wait
212 will drop the mutex while it waits, and obtain it again before
213 returning for whatever reason;
216 likewise, you must be holding the mutex around calls to
220 a process may return from condition-wait in several circumstances: it
221 is not guaranteed that the underlying condition has become true. You
222 must check that the resource is ready for whatever you want to do to
228 (defvar *buffer-queue* (make-waitqueue))
229 (defvar *buffer-lock* (make-mutex :name "buffer lock"))
231 (defvar *buffer* (list nil))
234 (with-mutex (*buffer-lock*)
236 (condition-wait *buffer-queue* *buffer-lock*)
238 (unless *buffer* (return))
239 (let ((head (car *buffer*)))
240 (setf *buffer* (cdr *buffer*))
241 (format t "reader ~A woke, read ~A~%"
242 *current-thread* head))))))
247 (with-mutex (*buffer-lock*)
250 (+ (char-code #\A) (random 26)))))))
251 (setf *buffer* (cons el *buffer*)))
252 (condition-notify *buffer-queue*))))
254 (make-thread #'writer)
255 (make-thread #'reader)
256 (make-thread #'reader)
259 @include struct-sb-thread-waitqueue.texinfo
260 @include fun-sb-thread-make-waitqueue.texinfo
261 @include fun-sb-thread-waitqueue-name.texinfo
262 @include fun-sb-thread-condition-wait.texinfo
263 @include fun-sb-thread-condition-notify.texinfo
264 @include fun-sb-thread-condition-broadcast.texinfo
267 @comment node-name, next, previous, up
270 These are based on the Linux kernel barrier design, which is in turn
271 based on the Alpha CPU memory model. They are presently implemented for
272 x86, x86-64, and PPC systems, and behave as compiler barriers on all
275 In addition to explicit use of the @code{sb-thread:barrier} macro, the
276 following functions and macros also serve as @code{:memory} barriers:
280 @code{sb-ext:atomic-decf} and @code{sb-ext:atomic-incf}.
282 @code{sb-ext:compare-and-swap}.
284 @code{sb-thread:get-mutex}, @code{sb-thread:release-mutex},
285 @code{sb-thread:with-mutex} and @code{sb-thread:with-recursive-lock}.
287 @code{sb-thread:signal-semaphore}, @code{sb-thread:try-semaphore} and
288 @code{sb-thread:wait-on-semaphore}.
290 @code{sb-thread:condition-wait}, @code{sb-thread:condition-notify} and
291 @code{sb-thread:condition-broadcast}.
294 @include macro-sb-thread-barrier.texinfo
296 @node Sessions/Debugging
297 @comment node-name, next, previous, up
298 @section Sessions/Debugging
300 If the user has multiple views onto the same Lisp image (for example,
301 using multiple terminals, or a windowing system, or network access)
302 they are typically set up as multiple @dfn{sessions} such that each
303 view has its own collection of foreground/background/stopped threads.
304 A thread which wishes to create a new session can use
305 @code{sb-thread:with-new-session} to remove itself from the current
306 session (which it shares with its parent and siblings) and create a
308 # See also @code{sb-thread:make-listener-thread}.
310 Within a single session, threads arbitrate between themselves for the
311 user's attention. A thread may be in one of three notional states:
312 foreground, background, or stopped. When a background process
313 attempts to print a repl prompt or to enter the debugger, it will stop
314 and print a message saying that it has stopped. The user at his
315 leisure may switch to that thread to find out what it needs. If a
316 background thread enters the debugger, selecting any restart will put
317 it back into the background before it resumes. Arbitration for the
318 input stream is managed by calls to @code{sb-thread:get-foreground}
319 (which may block) and @code{sb-thread:release-foreground}.
321 @code{sb-ext:quit} terminates all threads in the current session, but
322 leaves other sessions running.
324 @node Foreign threads
325 @comment node-name, next, previous, up
326 @section Foreign threads
328 Direct calls to @code{pthread_create} (instead of @code{MAKE-THREAD})
329 create threads that SBCL is not aware of, these are called foreign
330 threads. Currently, it is not possible to run Lisp code in such
331 threads. This means that the Lisp side signal handlers cannot work.
332 The best solution is to start foreign threads with signals blocked,
333 but since third party libraries may create threads, it is not always
334 feasible to do so. As a workaround, upon receiving a signal in a
335 foreign thread, SBCL changes the thread's sigmask to block all signals
336 that it wants to handle and resends the signal to the current process
337 which should land in a thread that does not block it, that is, a Lisp
340 The resignalling trick cannot work for synchronously triggered signals
341 (SIGSEGV and co), take care not to trigger any. Resignalling for
342 synchronously triggered signals in foreign threads is subject to
343 @code{--lose-on-corruption}, see @ref{Runtime Options}.
345 @node Implementation (Linux x86/x86-64)
346 @comment node-name, next, previous, up
347 @section Implementation (Linux x86/x86-64)
349 Threading is implemented using pthreads and some Linux specific bits
352 On x86 the per-thread local bindings for special variables is achieved
353 using the %fs segment register to point to a per-thread storage area.
354 This may cause interesting results if you link to foreign code that
355 expects threading or creates new threads, and the thread library in
356 question uses %fs in an incompatible way. On x86-64 the r12 register
359 Queues require the @code{sys_futex()} system call to be available:
360 this is the reason for the NPTL requirement. We test at runtime that
361 this system call exists.
363 Garbage collection is done with the existing Conservative Generational
364 GC. Allocation is done in small (typically 8k) regions: each thread
365 has its own region so this involves no stopping. However, when a
366 region fills, a lock must be obtained while another is allocated, and
367 when a collection is required, all processes are stopped. This is
368 achieved by sending them signals, which may make for interesting
369 behaviour if they are interrupted in system calls. The streams
370 interface is believed to handle the required system call restarting
371 correctly, but this may be a consideration when making other blocking
372 calls e.g. from foreign library code.
374 Large amounts of the SBCL library have not been inspected for
375 thread-safety. Some of the obviously unsafe areas have large locks
376 around them, so compilation and fasl loading, for example, cannot be
377 parallelized. Work is ongoing in this area.
379 A new thread by default is created in the same POSIX process group and
380 session as the thread it was created by. This has an impact on
381 keyboard interrupt handling: pressing your terminal's intr key
382 (typically @kbd{Control-C}) will interrupt all processes in the
383 foreground process group, including Lisp threads that SBCL considers
384 to be notionally `background'. This is undesirable, so background
385 threads are set to ignore the SIGINT signal.
387 @code{sb-thread:make-listener-thread} in addition to creating a new
388 Lisp session makes a new POSIX session, so that pressing
389 @kbd{Control-C} in one window will not interrupt another listener -
390 this has been found to be embarrassing.