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 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.
21 * Waitqueue/condition variables::
22 * Sessions/Debugging::
24 * Implementation (Linux x86/x86-64)::
27 @node Threading basics
28 @comment node-name, next, previous, up
29 @section Threading basics
32 (make-thread (lambda () (write-line "Hello, world")))
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
49 @node Special Variables
50 @comment node-name, next, previous, up
51 @section Special Variables
53 The interaction of special variables with multiple threads is mostly
54 as one would expect, with behaviour very similar to other
59 global special values are visible across all threads;
61 bindings (e.g. using LET) are local to the thread;
63 threads do not inherit dynamic bindings from the parent thread
66 The last point means that
71 (sb-thread:make-thread (lambda () (print *x*))))
74 prints @code{0} and not @code{1} as of 0.9.6.
77 @comment node-name, next, previous, up
78 @section Mutex Support
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.
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.
90 (defpackage :demo (:use "CL" "SB-THREAD" "SB-EXT"))
94 (defvar *a-mutex* (make-mutex :name "my lock"))
97 (format t "Thread ~A running ~%" *current-thread*)
98 (with-mutex (*a-mutex*)
99 (format t "Thread ~A got the lock~%" *current-thread*)
101 (format t "Thread ~A dropped lock, dying now~%" *current-thread*))
103 (make-thread #'thread-fn)
104 (make-thread #'thread-fn)
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
117 @comment node-name, next, previous, up
120 described here should be considered
121 experimental, subject to API changes without notice.
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
130 @node Waitqueue/condition variables
131 @comment node-name, next, previous, up
132 @section Waitqueue/condition variables
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.
142 There are three components:
146 the condition itself (not represented in code)
149 the condition variable (a.k.a waitqueue) which proxies for it
152 a lock to hold while testing the condition
155 Important stuff to be aware of:
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;
164 likewise, you must be holding the mutex around calls to
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
176 (defvar *buffer-queue* (make-waitqueue))
177 (defvar *buffer-lock* (make-mutex :name "buffer lock"))
179 (defvar *buffer* (list nil))
182 (with-mutex (*buffer-lock*)
184 (condition-wait *buffer-queue* *buffer-lock*)
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))))))
195 (with-mutex (*buffer-lock*)
198 (+ (char-code #\A) (random 26)))))))
199 (setf *buffer* (cons el *buffer*)))
200 (condition-notify *buffer-queue*))))
202 (make-thread #'writer)
203 (make-thread #'reader)
204 (make-thread #'reader)
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
214 @node Sessions/Debugging
215 @comment node-name, next, previous, up
216 @section Sessions/Debugging
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
226 # See also @code{sb-thread:make-listener-thread}.
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}.
239 @code{sb-ext:quit} terminates all threads in the current session, but
240 leaves other sessions running.
242 @node Foreign threads
243 @comment node-name, next, previous, up
244 @section Foreign threads
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
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}.
263 @node Implementation (Linux x86/x86-64)
264 @comment node-name, next, previous, up
265 @section Implementation (Linux x86/x86-64)
267 Threading is implemented using pthreads and some Linux specific bits
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
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.
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.
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.
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.
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.