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, and x86 SunOS (Solaris). On these platforms threads
16 must be explicitly enabled at build-time, see @file{INSTALL} for
24 * Waitqueue/condition variables::
25 * Sessions/Debugging::
27 * Implementation (Linux x86/x86-64)::
30 @node Threading basics
31 @comment node-name, next, previous, up
32 @section Threading basics
35 (make-thread (lambda () (write-line "Hello, world")))
38 @subsection Thread Objects
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
46 @subsection Making, Joining, and Yielding Threads
48 @include fun-sb-thread-make-thread.texinfo
49 @include fun-sb-thread-thread-yield.texinfo
50 @include fun-sb-thread-join-thread.texinfo
52 @subsection Asynchronous Operations
54 @include fun-sb-thread-interrupt-thread.texinfo
55 @include fun-sb-thread-terminate-thread.texinfo
57 @subsection Miscellaneous Operations
59 @include fun-sb-thread-symbol-value-in-thread.texinfo
61 @subsection Error Conditions
63 @include condition-sb-thread-thread-error.texinfo
64 @include fun-sb-thread-thread-error-thread.texinfo
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
70 @node Special Variables
71 @comment node-name, next, previous, up
72 @section Special Variables
74 The interaction of special variables with multiple threads is mostly
75 as one would expect, with behaviour very similar to other
80 global special values are visible across all threads;
82 bindings (e.g. using LET) are local to the thread;
84 threads do not inherit dynamic bindings from the parent thread
87 The last point means that
92 (sb-thread:make-thread (lambda () (print *x*))))
95 prints @code{0} and not @code{1} as of 0.9.6.
98 @comment node-name, next, previous, up
99 @section Mutex Support
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.
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.
111 (defpackage :demo (:use "CL" "SB-THREAD" "SB-EXT"))
115 (defvar *a-mutex* (make-mutex :name "my lock"))
118 (format t "Thread ~A running ~%" *current-thread*)
119 (with-mutex (*a-mutex*)
120 (format t "Thread ~A got the lock~%" *current-thread*)
122 (format t "Thread ~A dropped lock, dying now~%" *current-thread*))
124 (make-thread #'thread-fn)
125 (make-thread #'thread-fn)
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
138 @comment node-name, next, previous, up
141 described here should be considered
142 experimental, subject to API changes without notice.
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
151 @node Waitqueue/condition variables
152 @comment node-name, next, previous, up
153 @section Waitqueue/condition variables
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.
163 There are three components:
167 the condition itself (not represented in code)
170 the condition variable (a.k.a waitqueue) which proxies for it
173 a lock to hold while testing the condition
176 Important stuff to be aware of:
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;
185 likewise, you must be holding the mutex around calls to
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
197 (defvar *buffer-queue* (make-waitqueue))
198 (defvar *buffer-lock* (make-mutex :name "buffer lock"))
200 (defvar *buffer* (list nil))
203 (with-mutex (*buffer-lock*)
205 (condition-wait *buffer-queue* *buffer-lock*)
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))))))
216 (with-mutex (*buffer-lock*)
219 (+ (char-code #\A) (random 26)))))))
220 (setf *buffer* (cons el *buffer*)))
221 (condition-notify *buffer-queue*))))
223 (make-thread #'writer)
224 (make-thread #'reader)
225 (make-thread #'reader)
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
235 @node Sessions/Debugging
236 @comment node-name, next, previous, up
237 @section Sessions/Debugging
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
247 # See also @code{sb-thread:make-listener-thread}.
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}.
260 @code{sb-ext:quit} terminates all threads in the current session, but
261 leaves other sessions running.
263 @node Foreign threads
264 @comment node-name, next, previous, up
265 @section Foreign threads
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
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}.
284 @node Implementation (Linux x86/x86-64)
285 @comment node-name, next, previous, up
286 @section Implementation (Linux x86/x86-64)
288 Threading is implemented using pthreads and some Linux specific bits
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
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.
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.
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.
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.
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.