SBCL supports a fairly low-level threading interface that maps onto
the host operating system's concept of threads or lightweight
processes. This means that threads may take advantage of hardware
-multiprocessing on machines that have more than one CPU, but it does
+multiprocessing on machines that have more than one CPU, but it does
not allow Lisp control of the scheduler. This is found in the
SB-THREAD package.
-This requires x86 and Linux kernel 2.6 or systems with NPTL backports.
+This requires Linux (2.6+ or systems with NPTL backports) running on the
+x86 or x86-64 architecture, or SunOS (Solaris) on the x86. Support for
+threading on Darwin (Mac OS X) and FreeBSD on the x86 is experimental.
@menu
-* Special Variables::
-* Mutex Support::
-* Waitqueue/condition variables::
-* Sessions/Debugging::
-* Implementation (Linux x86)::
+* Threading basics::
+* Special Variables::
+* Mutex Support::
+* Semaphores::
+* Waitqueue/condition variables::
+* Sessions/Debugging::
+* Implementation (Linux x86)::
@end menu
+@node Threading basics
+@comment node-name, next, previous, up
+@section Threading basics
+
+@lisp
+(make-thread (lambda () (write-line "Hello, world")))
+@end lisp
+
+@include struct-sb-thread-thread.texinfo
+@include var-sb-thread-star-current-thread-star.texinfo
+@include fun-sb-thread-make-thread.texinfo
+@include fun-sb-thread-join-thread.texinfo
+@include condition-sb-thread-join-thread-error.texinfo
+@include fun-sb-thread-join-thread-error-thread.texinfo
+@include fun-sb-thread-thread-alive-p.texinfo
+@include fun-sb-thread-list-all-threads.texinfo
+@include condition-sb-thread-interrupt-thread-error.texinfo
+@include fun-sb-thread-interrupt-thread-error-thread.texinfo
+@include fun-sb-thread-interrupt-thread.texinfo
+@include fun-sb-thread-terminate-thread.texinfo
+@include fun-sb-thread-thread-yield.texinfo
+
@node Special Variables
@comment node-name, next, previous, up
@section Special Variables
The interaction of special variables with multiple threads is mostly
-as one would expect, but users of other Lisps are warned that the
-behaviour of locally bound specials differs in places from what they
-may expect.
+as one would expect, with behaviour very similar to other
+implementations.
@itemize
-@item
+@item
global special values are visible across all threads;
@item
bindings (e.g. using LET) are local to the thread;
@item
-initial values in a new thread are taken from the thread that created it.
+threads do not inherit dynamic bindings from the parent thread
@end itemize
+The last point means that
+
+@lisp
+(defparameter *x* 0)
+(let ((*x* 1))
+ (sb-thread:make-thread (lambda () (print *x*))))
+@end lisp
+
+prints @code{0} and not @code{1} as of 0.9.6.
+
@node Mutex Support
@comment node-name, next, previous, up
@section Mutex Support
(with-mutex (*a-mutex*)
(format t "Thread ~A got the lock~%" *current-thread*)
(sleep (random 5)))
- (format t "Thread ~A dropped lock, dying now~%" *current-thread*)))
+ (format t "Thread ~A dropped lock, dying now~%" *current-thread*))
(make-thread #'thread-fn)
(make-thread #'thread-fn)
-
@end lisp
+@include struct-sb-thread-mutex.texinfo
+@include fun-sb-thread-make-mutex.texinfo
+@include fun-sb-thread-mutex-name.texinfo
+@include fun-sb-thread-mutex-value.texinfo
+@include fun-sb-thread-get-mutex.texinfo
+@include fun-sb-thread-release-mutex.texinfo
+@include macro-sb-thread-with-mutex.texinfo
+@include macro-sb-thread-with-recursive-lock.texinfo
+
+@node Semaphores
+@comment node-name, next, previous, up
+@section Semaphores
+
+described here should be considered
+experimental, subject to API changes without notice.
+
+@include struct-sb-thread-semaphore.texinfo
+@include fun-sb-thread-make-semaphore.texinfo
+@include fun-sb-thread-semaphore-count.texinfo
+@include fun-sb-thread-semaphore-name.texinfo
+@include fun-sb-thread-signal-semaphore.texinfo
+@include fun-sb-thread-wait-on-semaphore.texinfo
+
@node Waitqueue/condition variables
@comment node-name, next, previous, up
@section Waitqueue/condition variables
There are three components:
@itemize
-@item
+@item
the condition itself (not represented in code)
-@item
+@item
the condition variable (a.k.a waitqueue) which proxies for it
-@item
-a lock to hold while testing the condition
+@item
+a lock to hold while testing the condition
@end itemize
Important stuff to be aware of:
@itemize
-@item
+@item
when calling condition-wait, you must hold the mutex. condition-wait
will drop the mutex while it waits, and obtain it again before
returning for whatever reason;
-@item
+@item
likewise, you must be holding the mutex around calls to
condition-notify;
-@item
+@item
a process may return from condition-wait in several circumstances: it
is not guaranteed that the underlying condition has become true. You
must check that the resource is ready for whatever you want to do to
(unless *buffer* (return))
(let ((head (car *buffer*)))
(setf *buffer* (cdr *buffer*))
- (format t "reader ~A woke, read ~A~%"
+ (format t "reader ~A woke, read ~A~%"
*current-thread* head))))))
(defun writer ()
(sleep (random 5))
(with-mutex (*buffer-lock*)
(let ((el (intern
- (string (code-char
+ (string (code-char
(+ (char-code #\A) (random 26)))))))
(setf *buffer* (cons el *buffer*)))
(condition-notify *buffer-queue*))))
(make-thread #'writer)
(make-thread #'reader)
-(make-thread #'reader)
-
+(make-thread #'reader)
@end lisp
+@include struct-sb-thread-waitqueue.texinfo
+@include fun-sb-thread-make-waitqueue.texinfo
+@include fun-sb-thread-waitqueue-name.texinfo
+@include fun-sb-thread-condition-wait.texinfo
+@include fun-sb-thread-condition-notify.texinfo
+@include fun-sb-thread-condition-broadcast.texinfo
+
@node Sessions/Debugging
@comment node-name, next, previous, up
@section Sessions/Debugging
A thread which wishes to create a new session can use
@code{sb-thread:with-new-session} to remove itself from the current
session (which it shares with its parent and siblings) and create a
-fresh one.
+fresh one.
# See also @code{sb-thread:make-listener-thread}.
Within a single session, threads arbitrate between themselves for the
@node Implementation (Linux x86)
@comment node-name, next, previous, up
-@section Implementation (Linux x86)
-
-On Linux x86, threading is implemented using @code{clone()} and does
-not involve pthreads. This is not because there is anything wrong
-with pthreads @emph{per se}, but there is plenty wrong (from our
-perspective) with LinuxThreads. SBCL threads are mapped 1:1 onto
-Linux tasks which share a VM but nothing else - each has its own
-process id and can be seen in e.g. @command{ps} output.
-
-Per-thread local bindings for special variables is achieved using the
-%fs segment register to point to a per-thread storage area. This may
-cause interesting results if you link to foreign code that expects
-threading or creates new threads, and the thread library in question
-uses %fs in an incompatible way.
+@section Implementation (Linux x86/x86-64)
+
+Threading is implemented using pthreads and some Linux specific bits
+like futexes.
+
+On x86 the per-thread local bindings for special variables is achieved
+using the %fs segment register to point to a per-thread storage area.
+This may cause interesting results if you link to foreign code that
+expects threading or creates new threads, and the thread library in
+question uses %fs in an incompatible way. On x86-64 the r12 register
+has a similar role.
Queues require the @code{sys_futex()} system call to be available:
this is the reason for the NPTL requirement. We test at runtime that
projects / sbcl.git / blobdiff