tests: better reports when /bin/ed is not present.

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

diff --git a/doc/manual/threading.texinfo b/doc/manual/threading.texinfo
index 5a6bfb2..f8f77da 100644 (file)
--- a/doc/manual/threading.texinfo
+++ b/doc/manual/threading.texinfo
@@ -44,12 +44,16 @@ directions.
 @include fun-sb-thread-list-all-threads.texinfo
 @include fun-sb-thread-thread-alive-p.texinfo
 @include fun-sb-thread-thread-name.texinfo
+@include fun-sb-thread-main-thread-p.texinfo
+@include fun-sb-thread-main-thread.texinfo
 
-@subsection Making, Joining, and Yielding Threads
+@subsection Making, Returning From, Joining, and Yielding Threads
 
 @include fun-sb-thread-make-thread.texinfo
-@include fun-sb-thread-thread-yield.texinfo
+@include macro-sb-thread-return-from-thread.texinfo
+@include fun-sb-thread-abort-thread.texinfo
 @include fun-sb-thread-join-thread.texinfo
+@include fun-sb-thread-thread-yield.texinfo
 
 @subsection Asynchronous Operations
 
@@ -100,17 +104,26 @@ prints @code{0} and not @code{1} as of 0.9.6.
 @comment  node-name,  next,  previous,  up
 @section Atomic Operations
 
-SBCL provides a few special purpose atomic operations, particularly
-useful for implementing lockless algorithms.
+Following atomic operations are particularly useful for implementing
+lockless algorithms.
 
 @include macro-sb-ext-atomic-decf.texinfo
 @include macro-sb-ext-atomic-incf.texinfo
+@include macro-sb-ext-atomic-pop.texinfo
+@include macro-sb-ext-atomic-push.texinfo
+@include macro-sb-ext-atomic-update.texinfo
 @include macro-sb-ext-compare-and-swap.texinfo
 
-@subsection CAS Protocol
+@unnumberedsubsec CAS Protocol
+
+Our @code{compare-and-swap} is user-extensible using a protocol
+similar to @code{setf}, allowing users to add CAS support to new
+places via e.g. @code{defcas}.
 
-Our @code{compare-and-swap} is user-extensible using a protocol similar
-to @code{setf}:
+At the same time, new atomic operations can be built on top of CAS
+using @code{get-cas-expansion}. See @code{atomic-update},
+@code{atomic-push}, and €@code{atomic-pop} for example of how to do
+this.
 
 @include macro-sb-ext-cas.texinfo
 @include macro-sb-ext-define-cas-expander.texinfo
@@ -126,10 +139,6 @@ thread is allowed to hold the mutex, others which attempt to take it
 will be made to wait until it's free. Threads are woken in the order
 that they go to sleep.
 
-There isn't a timeout on mutex acquisition, but the usual WITH-TIMEOUT
-macro (which throws a TIMEOUT condition after n seconds) can be used
-if you want a bounded wait.
-
 @lisp
 (defpackage :demo (:use "CL" "SB-THREAD" "SB-EXT"))
 
@@ -149,28 +158,37 @@ if you want a bounded wait.
 @end lisp
 
 @include struct-sb-thread-mutex.texinfo
+
+@include macro-sb-thread-with-mutex.texinfo
+@include macro-sb-thread-with-recursive-lock.texinfo
+
 @include fun-sb-thread-make-mutex.texinfo
 @include fun-sb-thread-mutex-name.texinfo
+@include fun-sb-thread-mutex-owner.texinfo
 @include fun-sb-thread-mutex-value.texinfo
-@include fun-sb-thread-get-mutex.texinfo
+@include fun-sb-thread-grab-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.
+Semaphores are among other things useful for keeping track of a
+countable resource, e.g. messages in a queue, and sleep when the
+resource is exhausted.
 
 @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-try-semaphore.texinfo
 @include fun-sb-thread-wait-on-semaphore.texinfo
+@include fun-sb-thread-try-semaphore.texinfo
+@include fun-sb-thread-semaphore-count.texinfo
+@include fun-sb-thread-semaphore-name.texinfo
+
+@include struct-sb-thread-semaphore-notification.texinfo
+@include fun-sb-thread-make-semaphore-notification.texinfo
+@include fun-sb-thread-semaphore-notification-status.texinfo
+@include fun-sb-thread-clear-semaphore-notification.texinfo
 
 @node Waitqueue/condition variables
 @comment  node-name,  next,  previous,  up
@@ -191,7 +209,7 @@ There are three components:
 the condition itself (not represented in code)
 
 @item
-the condition variable (a.k.a waitqueue) which proxies for it
+the condition variable (a.k.a. waitqueue) which proxies for it
 
 @item
 a lock to hold while testing the condition
@@ -270,11 +288,12 @@ following functions and macros also serve as @code{:memory} barriers:
 
 @itemize
 @item
-@code{sb-ext:atomic-decf} and @code{sb-ext:atomic-incf}.
+@code{sb-ext:atomic-decf}, @code{sb-ext:atomic-incf}, @code{sb-ext:atomic-push},
+and @code{sb-ext:atomic-pop}.
 @item
 @code{sb-ext:compare-and-swap}.
 @item
-@code{sb-thread:get-mutex}, @code{sb-thread:release-mutex},
+@code{sb-thread:grab-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
@@ -311,9 +330,6 @@ it back into the background before it resumes.  Arbitration for the
 input stream is managed by calls to @code{sb-thread:get-foreground}
 (which may block) and @code{sb-thread:release-foreground}.
 
-@code{sb-ext:quit} terminates all threads in the current session, but
-leaves other sessions running.
-
 @node Foreign threads
 @comment  node-name,  next,  previous,  up
 @section Foreign threads