0.9.11.4
[sbcl.git] / doc / manual / threading.texinfo
1 @node  Threading
2 @comment  node-name,  next,  previous,  up
3 @chapter Threading
4
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
10 SB-THREAD package.
11
12 This requires x86/x86-64 and Linux kernel 2.6 or systems with NPTL
13 backports.
14
15 @menu
16 * Threading basics::            
17 * Special Variables::           
18 * Mutex Support::               
19 * Waitqueue/condition variables::  
20 * Sessions/Debugging::          
21 * Implementation (Linux x86)::  
22 @end menu
23
24 @node Threading basics
25 @comment  node-name,  next,  previous,  up
26 @section Threading basics
27
28 @lisp
29 (make-thread (lambda () (write-line "Hello, world")))
30 @end lisp
31
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.texinfo
40 @include fun-sb-thread-terminate-thread.texinfo
41
42 @node Special Variables
43 @comment  node-name,  next,  previous,  up
44 @section Special Variables
45
46 The interaction of special variables with multiple threads is mostly
47 as one would expect, with behaviour very similar to other
48 implementations.
49
50 @itemize
51 @item
52 global special values are visible across all threads;
53 @item
54 bindings (e.g. using LET) are local to the thread;
55 @item
56 threads do not inherit dynamic bindings from the parent thread
57 @end itemize
58
59 The last point means that
60
61 @lisp
62 (defparameter *x* 0)
63 (let ((*x* 1))
64   (sb-thread:make-thread (lambda () (print *x*))))
65 @end lisp
66
67 prints @code{0} and not @code{1} as of 0.9.6.
68
69 @node Mutex Support
70 @comment  node-name,  next,  previous,  up
71 @section Mutex Support
72
73 Mutexes are used for controlling access to a shared resource. One
74 thread is allowed to hold the mutex, others which attempt to take it
75 will be made to wait until it's free. Threads are woken in the order
76 that they go to sleep.
77
78 There isn't a timeout on mutex acquisition, but the usual WITH-TIMEOUT
79 macro (which throws a TIMEOUT condition after n seconds) can be used
80 if you want a bounded wait.
81
82 @lisp
83 (defpackage :demo (:use "CL" "SB-THREAD" "SB-EXT"))
84
85 (in-package :demo)
86
87 (defvar *a-mutex* (make-mutex :name "my lock"))
88
89 (defun thread-fn ()
90   (format t "Thread ~A running ~%" *current-thread*)
91   (with-mutex (*a-mutex*)
92     (format t "Thread ~A got the lock~%" *current-thread*)
93     (sleep (random 5)))
94   (format t "Thread ~A dropped lock, dying now~%" *current-thread*)))
95
96 (make-thread #'thread-fn)
97 (make-thread #'thread-fn)
98 @end lisp
99
100 @include struct-sb-thread-mutex.texinfo
101 @include fun-sb-thread-make-mutex.texinfo
102 @include fun-sb-thread-mutex-name.texinfo
103 @include fun-sb-thread-mutex-value.texinfo
104 @include fun-sb-thread-get-mutex.texinfo
105 @include fun-sb-thread-release-mutex.texinfo
106 @include macro-sb-thread-with-mutex.texinfo
107 @include macro-sb-thread-with-recursive-lock.texinfo
108
109 @node Waitqueue/condition variables
110 @comment  node-name,  next,  previous,  up
111 @section Waitqueue/condition variables
112
113 These are based on the POSIX condition variable design, hence the
114 annoyingly CL-conflicting name. For use when you want to check a
115 condition and sleep until it's true. For example: you have a shared
116 queue, a writer process checking ``queue is empty'' and one or more
117 readers that need to know when ``queue is not empty''. It sounds
118 simple, but is astonishingly easy to deadlock if another process runs
119 when you weren't expecting it to.
120
121 There are three components:
122
123 @itemize
124 @item 
125 the condition itself (not represented in code)
126
127 @item 
128 the condition variable (a.k.a waitqueue) which proxies for it
129
130 @item 
131 a lock to hold while testing the condition 
132 @end itemize
133
134 Important stuff to be aware of:
135
136 @itemize
137 @item 
138 when calling condition-wait, you must hold the mutex. condition-wait
139 will drop the mutex while it waits, and obtain it again before
140 returning for whatever reason;
141
142 @item 
143 likewise, you must be holding the mutex around calls to
144 condition-notify;
145
146 @item 
147 a process may return from condition-wait in several circumstances: it
148 is not guaranteed that the underlying condition has become true. You
149 must check that the resource is ready for whatever you want to do to
150 it.
151
152 @end itemize
153
154 @lisp
155 (defvar *buffer-queue* (make-waitqueue))
156 (defvar *buffer-lock* (make-mutex :name "buffer lock"))
157
158 (defvar *buffer* (list nil))
159
160 (defun reader ()
161   (with-mutex (*buffer-lock*)
162     (loop
163      (condition-wait *buffer-queue* *buffer-lock*)
164      (loop
165       (unless *buffer* (return))
166       (let ((head (car *buffer*)))
167         (setf *buffer* (cdr *buffer*))
168         (format t "reader ~A woke, read ~A~%" 
169                 *current-thread* head))))))
170
171 (defun writer ()
172   (loop
173    (sleep (random 5))
174    (with-mutex (*buffer-lock*)
175      (let ((el (intern
176                 (string (code-char 
177                          (+ (char-code #\A) (random 26)))))))
178        (setf *buffer* (cons el *buffer*)))
179      (condition-notify *buffer-queue*))))
180
181 (make-thread #'writer)
182 (make-thread #'reader)
183 (make-thread #'reader)       
184 @end lisp
185
186 @include struct-sb-thread-waitqueue.texinfo
187 @include fun-sb-thread-make-waitqueue.texinfo
188 @include fun-sb-thread-waitqueue-name.texinfo
189 @include fun-sb-thread-condition-wait.texinfo
190 @include fun-sb-thread-condition-notify.texinfo
191 @include fun-sb-thread-condition-broadcast.texinfo
192
193 @node Sessions/Debugging
194 @comment  node-name,  next,  previous,  up
195 @section Sessions/Debugging
196
197 If the user has multiple views onto the same Lisp image (for example,
198 using multiple terminals, or a windowing system, or network access)
199 they are typically set up as multiple @dfn{sessions} such that each
200 view has its own collection of foreground/background/stopped threads.
201 A thread which wishes to create a new session can use
202 @code{sb-thread:with-new-session} to remove itself from the current
203 session (which it shares with its parent and siblings) and create a
204 fresh one.  
205 # See also @code{sb-thread:make-listener-thread}.
206
207 Within a single session, threads arbitrate between themselves for the
208 user's attention.  A thread may be in one of three notional states:
209 foreground, background, or stopped.  When a background process
210 attempts to print a repl prompt or to enter the debugger, it will stop
211 and print a message saying that it has stopped.  The user at his
212 leisure may switch to that thread to find out what it needs.  If a
213 background thread enters the debugger, selecting any restart will put
214 it back into the background before it resumes.  Arbitration for the
215 input stream is managed by calls to @code{sb-thread:get-foreground}
216 (which may block) and @code{sb-thread:release-foreground}.
217
218 @code{sb-ext:quit} terminates all threads in the current session, but
219 leaves other sessions running.
220
221 @node Implementation (Linux x86)
222 @comment  node-name,  next,  previous,  up
223 @section Implementation (Linux x86/x86-64)
224
225 Threading is implemented using pthreads and some Linux specific bits
226 like futexes.
227
228 On x86 the per-thread local bindings for special variables is achieved
229 using the %fs segment register to point to a per-thread storage area.
230 This may cause interesting results if you link to foreign code that
231 expects threading or creates new threads, and the thread library in
232 question uses %fs in an incompatible way. On x86-64 the r12 register
233 has a similar role.
234
235 Queues require the @code{sys_futex()} system call to be available:
236 this is the reason for the NPTL requirement.  We test at runtime that
237 this system call exists.
238
239 Garbage collection is done with the existing Conservative Generational
240 GC.  Allocation is done in small (typically 8k) regions: each thread
241 has its own region so this involves no stopping. However, when a
242 region fills, a lock must be obtained while another is allocated, and
243 when a collection is required, all processes are stopped.  This is
244 achieved by sending them signals, which may make for interesting
245 behaviour if they are interrupted in system calls.  The streams
246 interface is believed to handle the required system call restarting
247 correctly, but this may be a consideration when making other blocking
248 calls e.g. from foreign library code.
249
250 Large amounts of the SBCL library have not been inspected for
251 thread-safety.  Some of the obviously unsafe areas have large locks
252 around them, so compilation and fasl loading, for example, cannot be
253 parallelized.  Work is ongoing in this area.
254
255 A new thread by default is created in the same POSIX process group and
256 session as the thread it was created by.  This has an impact on
257 keyboard interrupt handling: pressing your terminal's intr key
258 (typically @kbd{Control-C}) will interrupt all processes in the
259 foreground process group, including Lisp threads that SBCL considers
260 to be notionally `background'.  This is undesirable, so background
261 threads are set to ignore the SIGINT signal.
262
263 @code{sb-thread:make-listener-thread} in addition to creating a new
264 Lisp session makes a new POSIX session, so that pressing
265 @kbd{Control-C} in one window will not interrupt another listener -
266 this has been found to be embarrassing.