X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fthreading.texinfo;h=b51ba34a902baa9477dd2e5a1e8d661680f06b4b;hb=d84e1dbbbf11e76663cfaa0b1a5b7591f39f01b6;hp=7e84de505c8eaec70dc3cdf1ddcf4ba35e7babb1;hpb=ce3fc26e7433d807ec953785cf4b8bb658f9a638;p=sbcl.git diff --git a/doc/manual/threading.texinfo b/doc/manual/threading.texinfo index 7e84de5..b51ba34 100644 --- a/doc/manual/threading.texinfo +++ b/doc/manual/threading.texinfo @@ -9,18 +9,24 @@ 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 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. +Threads are part of the default build on x86[-64] Linux only. + +They are also experimentally supported on: x86[-64] Darwin (Mac OS X), +x86[-64] FreeBSD, x86 SunOS (Solaris), and PPC Linux. On these platforms +threads must be explicitly enabled at build-time, see @file{INSTALL} for +directions. @menu -* Threading basics:: -* Special Variables:: -* Mutex Support:: -* Semaphores:: -* Waitqueue/condition variables:: -* Sessions/Debugging:: -* Implementation (Linux x86):: +* Threading basics:: +* Special Variables:: +* Atomic Operations:: +* Mutex Support:: +* Semaphores:: +* Waitqueue/condition variables:: +* Barriers:: +* Sessions/Debugging:: +* Foreign threads:: +* Implementation (Linux x86/x86-64):: @end menu @node Threading basics @@ -31,19 +37,38 @@ threading on Darwin (Mac OS X) and FreeBSD on the x86 is experimental. (make-thread (lambda () (write-line "Hello, world"))) @end lisp +@subsection Thread Objects + @include struct-sb-thread-thread.texinfo @include var-sb-thread-star-current-thread-star.texinfo +@include fun-sb-thread-list-all-threads.texinfo +@include fun-sb-thread-thread-alive-p.texinfo +@include fun-sb-thread-thread-name.texinfo + +@subsection Making, Joining, and Yielding Threads + @include fun-sb-thread-make-thread.texinfo +@include fun-sb-thread-thread-yield.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 + +@subsection Asynchronous Operations + @include fun-sb-thread-interrupt-thread.texinfo @include fun-sb-thread-terminate-thread.texinfo +@subsection Miscellaneous Operations + +@include fun-sb-thread-symbol-value-in-thread.texinfo + +@subsection Error Conditions + +@include condition-sb-thread-thread-error.texinfo +@include fun-sb-thread-thread-error-thread.texinfo + +@c @include condition-sb-thread-symbol-value-in-thread-error.texinfo +@include condition-sb-thread-interrupt-thread-error.texinfo +@include condition-sb-thread-join-thread-error.texinfo + @node Special Variables @comment node-name, next, previous, up @section Special Variables @@ -71,6 +96,17 @@ The last point means that prints @code{0} and not @code{1} as of 0.9.6. +@node Atomic Operations +@comment node-name, next, previous, up +@section Atomic Operations + +SBCL provides a few special purpose atomic operations, particularly +useful for implementing lockless algorithms. + +@include macro-sb-ext-atomic-decf.texinfo +@include macro-sb-ext-atomic-incf.texinfo +@include macro-sb-ext-compare-and-swap.texinfo + @node Mutex Support @comment node-name, next, previous, up @section Mutex Support @@ -115,7 +151,7 @@ if you want a bounded wait. @comment node-name, next, previous, up @section Semaphores -escribed here should be considered +described here should be considered experimental, subject to API changes without notice. @include struct-sb-thread-semaphore.texinfo @@ -123,6 +159,7 @@ experimental, subject to API changes without notice. @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-try-semaphore.texinfo @include fun-sb-thread-wait-on-semaphore.texinfo @node Waitqueue/condition variables @@ -209,6 +246,36 @@ it. @include fun-sb-thread-condition-notify.texinfo @include fun-sb-thread-condition-broadcast.texinfo +@node Barriers +@comment node-name, next, previous, up +@section Barriers + +These are based on the Linux kernel barrier design, which is in turn +based on the Alpha CPU memory model. They are presently implemented for +x86, x86-64, and PPC systems, and behave as compiler barriers on all +other CPUs. + +In addition to explicit use of the @code{sb-thread:barrier} macro, the +following functions and macros also serve as @code{:memory} barriers: + +@itemize +@item +@code{sb-ext:atomic-decf} and @code{sb-ext:atomic-incf}. +@item +@code{sb-ext:compare-and-swap}. +@item +@code{sb-thread:get-mutex}, @code{sb-thread:release-mutex}, +@code{sb-thread:with-mutex} and @code{sb-thread:with-recursive-lock}. +@item +@code{sb-thread:signal-semaphore}, @code{sb-thread:try-semaphore} and +@code{sb-thread:wait-on-semaphore}. +@item +@code{sb-thread:condition-wait}, @code{sb-thread:condition-notify} and +@code{sb-thread:condition-broadcast}. +@end itemize + +@include macro-sb-thread-barrier.texinfo + @node Sessions/Debugging @comment node-name, next, previous, up @section Sessions/Debugging @@ -237,7 +304,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)