X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fthreading.texinfo;h=759ab0f8fc8e6d8e463bda2b8edb38ffd5fecfa2;hb=0c5c2fec5aae5fc87fc392192b009d234ea99462;hp=944892a2c490394981ef7fcaab7651f9330caefb;hpb=94ea2b2082deaa0331dfb66fa6af6ca12dd8dc83;p=sbcl.git diff --git a/doc/manual/threading.texinfo b/doc/manual/threading.texinfo index 944892a..759ab0f 100644 --- a/doc/manual/threading.texinfo +++ b/doc/manual/threading.texinfo @@ -9,9 +9,12 @@ 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 +* Threading basics:: * Special Variables:: * Mutex Support:: * Waitqueue/condition variables:: @@ -19,24 +22,54 @@ This requires x86 and Linux kernel 2.6 or systems with NPTL backports. * 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 + @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 @@ -62,13 +95,21 @@ if you want a bounded wait. (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 Waitqueue/condition variables @comment node-name, next, previous, up @section Waitqueue/condition variables @@ -144,9 +185,15 @@ it. (make-thread #'writer) (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 @@ -177,20 +224,17 @@ leaves other sessions running. @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