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 x86/x86-64 and Linux kernel 2.6 or systems with NPTL
19 * Waitqueue/condition variables::
20 * Sessions/Debugging::
21 * Implementation (Linux x86)::
24 @node Threading basics
25 @comment node-name, next, previous, up
26 @section Threading basics
29 (make-thread (lambda () (write-line "Hello, world")))
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
43 @node Special Variables
44 @comment node-name, next, previous, up
45 @section Special Variables
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
54 global special values are visible across all threads;
56 bindings (e.g. using LET) are local to the thread;
58 initial values in a new thread are taken from the thread that created it.
61 The last point means that
66 (sb-thread:make-thread (lambda () (print *x*))))
72 @comment node-name, next, previous, up
73 @section Mutex Support
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.
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.
85 (defpackage :demo (:use "CL" "SB-THREAD" "SB-EXT"))
89 (defvar *a-mutex* (make-mutex :name "my lock"))
92 (format t "Thread ~A running ~%" *current-thread*)
93 (with-mutex (*a-mutex*)
94 (format t "Thread ~A got the lock~%" *current-thread*)
96 (format t "Thread ~A dropped lock, dying now~%" *current-thread*)))
98 (make-thread #'thread-fn)
99 (make-thread #'thread-fn)
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
111 @node Waitqueue/condition variables
112 @comment node-name, next, previous, up
113 @section Waitqueue/condition variables
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.
123 There are three components:
127 the condition itself (not represented in code)
130 the condition variable (a.k.a waitqueue) which proxies for it
133 a lock to hold while testing the condition
136 Important stuff to be aware of:
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;
145 likewise, you must be holding the mutex around calls to
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
157 (defvar *buffer-queue* (make-waitqueue))
158 (defvar *buffer-lock* (make-mutex :name "buffer lock"))
160 (defvar *buffer* (list nil))
163 (with-mutex (*buffer-lock*)
165 (condition-wait *buffer-queue* *buffer-lock*)
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))))))
176 (with-mutex (*buffer-lock*)
179 (+ (char-code #\A) (random 26)))))))
180 (setf *buffer* (cons el *buffer*)))
181 (condition-notify *buffer-queue*))))
183 (make-thread #'writer)
184 (make-thread #'reader)
185 (make-thread #'reader)
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
195 @node Sessions/Debugging
196 @comment node-name, next, previous, up
197 @section Sessions/Debugging
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
207 # See also @code{sb-thread:make-listener-thread}.
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}.
220 @code{sb-ext:quit} terminates all threads in the current session, but
221 leaves other sessions running.
223 @node Implementation (Linux x86)
224 @comment node-name, next, previous, up
225 @section Implementation (Linux x86/x86-64)
227 Threading is implemented using pthreads and some Linux specific bits
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
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.
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.
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.
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.
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.