1.0.36.11: Make slam.sh work on Win32.

[sbcl.git] / doc / manual / threading.texinfo

diff --git a/doc/manual/threading.texinfo b/doc/manual/threading.texinfo
index 7e84de5..2fbd8d8 100644 (file)
--- a/doc/manual/threading.texinfo
+++ b/doc/manual/threading.texinfo
@@ -9,18 +9,22 @@ 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, and x86 SunOS (Solaris). 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::           
+* Mutex Support::               
+* Semaphores::                  
+* Waitqueue/condition variables::  
+* Sessions/Debugging::          
+* Foreign threads::             
+* Implementation (Linux x86/x86-64)::  
 @end menu
 
 @node Threading basics
@@ -31,19 +35,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
@@ -115,7 +138,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
@@ -237,7 +260,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)