X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fthreading.texinfo;h=d1185e7db1aca47d09e714f12ce3a8f338d0bb37;hb=fd79e33e6b6dacdc52cf6668a5bb7adf75aad6c1;hp=784a96500bef3fbc1993e0f119475bf290a208c9;hpb=3de72ade2968588728e3fe09170af9f54075f126;p=sbcl.git diff --git a/doc/manual/threading.texinfo b/doc/manual/threading.texinfo index 784a965..d1185e7 100644 --- a/doc/manual/threading.texinfo +++ b/doc/manual/threading.texinfo @@ -5,20 +5,23 @@ 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/x86-64 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 -* Threading basics:: -* Special Variables:: -* Mutex Support:: -* Waitqueue/condition variables:: -* Sessions/Debugging:: -* Implementation (Linux x86):: +* Threading basics:: +* Special Variables:: +* Mutex Support:: +* Semaphores:: +* Waitqueue/condition variables:: +* Sessions/Debugging:: +* Foreign threads:: +* Implementation (Linux x86/x86-64):: @end menu @node Threading basics @@ -32,12 +35,16 @@ backports. @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 @@ -106,6 +113,20 @@ if you want a bounded wait. @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 @@ -121,29 +142,29 @@ when you weren't expecting it to. 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 @@ -165,7 +186,7 @@ it. (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 () @@ -173,14 +194,14 @@ it. (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 @@ -201,7 +222,7 @@ view has its own collection of foreground/background/stopped threads. 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 @@ -218,7 +239,28 @@ input stream is managed by calls to @code{sb-thread:get-foreground} @code{sb-ext:quit} terminates all threads in the current session, but leaves other sessions running. -@node Implementation (Linux x86) +@node Foreign threads +@comment node-name, next, previous, up +@section Foreign threads + +Direct calls to @code{pthread_create} (instead of @code{MAKE-THREAD}) +create threads that SBCL is not aware of, these are called foreign +threads. Currently, it is not possible to run Lisp code in such +threads. This means that the Lisp side signal handlers cannot work. +The best solution is to start foreign threads with signals blocked, +but since third party libraries may create threads, it is not always +feasible to do so. As a workaround, upon receiving a signal in a +foreign thread, SBCL changes the thread's sigmask to block all signals +that it wants to handle and resends the signal to the current process +which should land in a thread that does not block it, that is, a Lisp +thread. + +The resignalling trick cannot work for synchronously triggered signals +(SIGSEGV and co), take care not to trigger any. Resignalling for +synchronously triggered signals in foreign threads is subject to +@code{--lose-on-corruption}, see @ref{Runtime Options}. + +@node Implementation (Linux x86/x86-64) @comment node-name, next, previous, up @section Implementation (Linux x86/x86-64)