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
47 @include fun-sb-thread-main-thread-p.texinfo
48 @include fun-sb-thread-main-thread.texinfo
50 @subsection Making, Returning From, Joining, and Yielding Threads
52 @include fun-sb-thread-make-thread.texinfo
53 @include macro-sb-thread-return-from-thread.texinfo
54 @include fun-sb-thread-abort-thread.texinfo
55 @include fun-sb-thread-join-thread.texinfo
56 @include fun-sb-thread-thread-yield.texinfo
58 @subsection Asynchronous Operations
60 @include fun-sb-thread-interrupt-thread.texinfo
61 @include fun-sb-thread-terminate-thread.texinfo
63 @subsection Miscellaneous Operations
65 @include fun-sb-thread-symbol-value-in-thread.texinfo
67 @subsection Error Conditions
69 @include condition-sb-thread-thread-error.texinfo
70 @include fun-sb-thread-thread-error-thread.texinfo
72 @c @include condition-sb-thread-symbol-value-in-thread-error.texinfo
73 @include condition-sb-thread-interrupt-thread-error.texinfo
74 @include condition-sb-thread-join-thread-error.texinfo
76 @node Special Variables
77 @comment node-name, next, previous, up
78 @section Special Variables
80 The interaction of special variables with multiple threads is mostly
81 as one would expect, with behaviour very similar to other
86 global special values are visible across all threads;
88 bindings (e.g. using LET) are local to the thread;
90 threads do not inherit dynamic bindings from the parent thread
93 The last point means that
98 (sb-thread:make-thread (lambda () (print *x*))))
101 prints @code{0} and not @code{1} as of 0.9.6.
103 @node Atomic Operations
104 @comment node-name, next, previous, up
105 @section Atomic Operations
107 SBCL provides a few special purpose atomic operations, particularly
108 useful for implementing lockless algorithms.
110 @include macro-sb-ext-atomic-decf.texinfo
111 @include macro-sb-ext-atomic-incf.texinfo
112 @include macro-sb-ext-compare-and-swap.texinfo
114 @unnumberedsubsec CAS Protocol
116 Our @code{compare-and-swap} is user-extensible using a protocol similar
119 @include macro-sb-ext-cas.texinfo
120 @include macro-sb-ext-define-cas-expander.texinfo
121 @include macro-sb-ext-defcas.texinfo
122 @include fun-sb-ext-get-cas-expansion.texinfo
125 @comment node-name, next, previous, up
126 @section Mutex Support
128 Mutexes are used for controlling access to a shared resource. One
129 thread is allowed to hold the mutex, others which attempt to take it
130 will be made to wait until it's free. Threads are woken in the order
131 that they go to sleep.
133 There isn't a timeout on mutex acquisition, but the usual WITH-TIMEOUT
134 macro (which throws a TIMEOUT condition after n seconds) can be used
135 if you want a bounded wait.
138 (defpackage :demo (:use "CL" "SB-THREAD" "SB-EXT"))
142 (defvar *a-mutex* (make-mutex :name "my lock"))
145 (format t "Thread ~A running ~%" *current-thread*)
146 (with-mutex (*a-mutex*)
147 (format t "Thread ~A got the lock~%" *current-thread*)
149 (format t "Thread ~A dropped lock, dying now~%" *current-thread*))
151 (make-thread #'thread-fn)
152 (make-thread #'thread-fn)
155 @include struct-sb-thread-mutex.texinfo
156 @include fun-sb-thread-make-mutex.texinfo
157 @include fun-sb-thread-mutex-name.texinfo
158 @include fun-sb-thread-mutex-value.texinfo
159 @include fun-sb-thread-grab-mutex.texinfo
160 @include fun-sb-thread-release-mutex.texinfo
161 @include macro-sb-thread-with-mutex.texinfo
162 @include macro-sb-thread-with-recursive-lock.texinfo
163 @include fun-sb-thread-get-mutex.texinfo
166 @comment node-name, next, previous, up
169 Semaphores are among other things useful for keeping track of a
170 countable resource, eg. messages in a queue, and sleep when the
171 resource is exhausted.
173 @include struct-sb-thread-semaphore.texinfo
174 @include fun-sb-thread-make-semaphore.texinfo
175 @include fun-sb-thread-signal-semaphore.texinfo
176 @include fun-sb-thread-wait-on-semaphore.texinfo
177 @include fun-sb-thread-try-semaphore.texinfo
178 @include fun-sb-thread-semaphore-count.texinfo
179 @include fun-sb-thread-semaphore-name.texinfo
181 @include struct-sb-thread-semaphore-notification.texinfo
182 @include fun-sb-thread-make-semaphore-notification.texinfo
183 @include fun-sb-thread-semaphore-notification-status.texinfo
184 @include fun-sb-thread-clear-semaphore-notification.texinfo
186 @node Waitqueue/condition variables
187 @comment node-name, next, previous, up
188 @section Waitqueue/condition variables
190 These are based on the POSIX condition variable design, hence the
191 annoyingly CL-conflicting name. For use when you want to check a
192 condition and sleep until it's true. For example: you have a shared
193 queue, a writer process checking ``queue is empty'' and one or more
194 readers that need to know when ``queue is not empty''. It sounds
195 simple, but is astonishingly easy to deadlock if another process runs
196 when you weren't expecting it to.
198 There are three components:
202 the condition itself (not represented in code)
205 the condition variable (a.k.a waitqueue) which proxies for it
208 a lock to hold while testing the condition
211 Important stuff to be aware of:
215 when calling condition-wait, you must hold the mutex. condition-wait
216 will drop the mutex while it waits, and obtain it again before
217 returning for whatever reason;
220 likewise, you must be holding the mutex around calls to
224 a process may return from condition-wait in several circumstances: it
225 is not guaranteed that the underlying condition has become true. You
226 must check that the resource is ready for whatever you want to do to
232 (defvar *buffer-queue* (make-waitqueue))
233 (defvar *buffer-lock* (make-mutex :name "buffer lock"))
235 (defvar *buffer* (list nil))
238 (with-mutex (*buffer-lock*)
240 (condition-wait *buffer-queue* *buffer-lock*)
242 (unless *buffer* (return))
243 (let ((head (car *buffer*)))
244 (setf *buffer* (cdr *buffer*))
245 (format t "reader ~A woke, read ~A~%"
246 *current-thread* head))))))
251 (with-mutex (*buffer-lock*)
254 (+ (char-code #\A) (random 26)))))))
255 (setf *buffer* (cons el *buffer*)))
256 (condition-notify *buffer-queue*))))
258 (make-thread #'writer)
259 (make-thread #'reader)
260 (make-thread #'reader)
263 @include struct-sb-thread-waitqueue.texinfo
264 @include fun-sb-thread-make-waitqueue.texinfo
265 @include fun-sb-thread-waitqueue-name.texinfo
266 @include fun-sb-thread-condition-wait.texinfo
267 @include fun-sb-thread-condition-notify.texinfo
268 @include fun-sb-thread-condition-broadcast.texinfo
271 @comment node-name, next, previous, up
274 These are based on the Linux kernel barrier design, which is in turn
275 based on the Alpha CPU memory model. They are presently implemented for
276 x86, x86-64, and PPC systems, and behave as compiler barriers on all
279 In addition to explicit use of the @code{sb-thread:barrier} macro, the
280 following functions and macros also serve as @code{:memory} barriers:
284 @code{sb-ext:atomic-decf} and @code{sb-ext:atomic-incf}.
286 @code{sb-ext:compare-and-swap}.
288 @code{sb-thread:get-mutex}, @code{sb-thread:release-mutex},
289 @code{sb-thread:with-mutex} and @code{sb-thread:with-recursive-lock}.
291 @code{sb-thread:signal-semaphore}, @code{sb-thread:try-semaphore} and
292 @code{sb-thread:wait-on-semaphore}.
294 @code{sb-thread:condition-wait}, @code{sb-thread:condition-notify} and
295 @code{sb-thread:condition-broadcast}.
298 @include macro-sb-thread-barrier.texinfo
300 @node Sessions/Debugging
301 @comment node-name, next, previous, up
302 @section Sessions/Debugging
304 If the user has multiple views onto the same Lisp image (for example,
305 using multiple terminals, or a windowing system, or network access)
306 they are typically set up as multiple @dfn{sessions} such that each
307 view has its own collection of foreground/background/stopped threads.
308 A thread which wishes to create a new session can use
309 @code{sb-thread:with-new-session} to remove itself from the current
310 session (which it shares with its parent and siblings) and create a
312 # See also @code{sb-thread:make-listener-thread}.
314 Within a single session, threads arbitrate between themselves for the
315 user's attention. A thread may be in one of three notional states:
316 foreground, background, or stopped. When a background process
317 attempts to print a repl prompt or to enter the debugger, it will stop
318 and print a message saying that it has stopped. The user at his
319 leisure may switch to that thread to find out what it needs. If a
320 background thread enters the debugger, selecting any restart will put
321 it back into the background before it resumes. Arbitration for the
322 input stream is managed by calls to @code{sb-thread:get-foreground}
323 (which may block) and @code{sb-thread:release-foreground}.
325 @node Foreign threads
326 @comment node-name, next, previous, up
327 @section Foreign threads
329 Direct calls to @code{pthread_create} (instead of @code{MAKE-THREAD})
330 create threads that SBCL is not aware of, these are called foreign
331 threads. Currently, it is not possible to run Lisp code in such
332 threads. This means that the Lisp side signal handlers cannot work.
333 The best solution is to start foreign threads with signals blocked,
334 but since third party libraries may create threads, it is not always
335 feasible to do so. As a workaround, upon receiving a signal in a
336 foreign thread, SBCL changes the thread's sigmask to block all signals
337 that it wants to handle and resends the signal to the current process
338 which should land in a thread that does not block it, that is, a Lisp
341 The resignalling trick cannot work for synchronously triggered signals
342 (SIGSEGV and co), take care not to trigger any. Resignalling for
343 synchronously triggered signals in foreign threads is subject to
344 @code{--lose-on-corruption}, see @ref{Runtime Options}.
346 @node Implementation (Linux x86/x86-64)
347 @comment node-name, next, previous, up
348 @section Implementation (Linux x86/x86-64)
350 Threading is implemented using pthreads and some Linux specific bits
353 On x86 the per-thread local bindings for special variables is achieved
354 using the %fs segment register to point to a per-thread storage area.
355 This may cause interesting results if you link to foreign code that
356 expects threading or creates new threads, and the thread library in
357 question uses %fs in an incompatible way. On x86-64 the r12 register
360 Queues require the @code{sys_futex()} system call to be available:
361 this is the reason for the NPTL requirement. We test at runtime that
362 this system call exists.
364 Garbage collection is done with the existing Conservative Generational
365 GC. Allocation is done in small (typically 8k) regions: each thread
366 has its own region so this involves no stopping. However, when a
367 region fills, a lock must be obtained while another is allocated, and
368 when a collection is required, all processes are stopped. This is
369 achieved by sending them signals, which may make for interesting
370 behaviour if they are interrupted in system calls. The streams
371 interface is believed to handle the required system call restarting
372 correctly, but this may be a consideration when making other blocking
373 calls e.g. from foreign library code.
375 Large amounts of the SBCL library have not been inspected for
376 thread-safety. Some of the obviously unsafe areas have large locks
377 around them, so compilation and fasl loading, for example, cannot be
378 parallelized. Work is ongoing in this area.
380 A new thread by default is created in the same POSIX process group and
381 session as the thread it was created by. This has an impact on
382 keyboard interrupt handling: pressing your terminal's intr key
383 (typically @kbd{Control-C}) will interrupt all processes in the
384 foreground process group, including Lisp threads that SBCL considers
385 to be notionally `background'. This is undesirable, so background
386 threads are set to ignore the SIGINT signal.
388 @code{sb-thread:make-listener-thread} in addition to creating a new
389 Lisp session makes a new POSIX session, so that pressing
390 @kbd{Control-C} in one window will not interrupt another listener -
391 this has been found to be embarrassing.