(Higher level thread procedures): Rewrite.

1 files changed, 39 insertions, 39 deletions

diff --git a/doc/scheme-scheduling.texi b/doc/scheme-scheduling.texi
index c9756eb33..af10144af 100644
--- a/doc/scheme-scheduling.texi
+++ b/doc/scheme-scheduling.texi
@@ -225,16 +225,16 @@ executed in a new dynamic root.
 @c are in sync.
 
 @c begin (texi-doc-string "guile" "call-with-new-thread")
-@deffn primitive call-with-new-thread thunk error-thunk
+@deffn primitive call-with-new-thread thunk error-handler
 Evaluate @code{(thunk)} in a new thread, and new dynamic context,
 returning a new thread object representing the thread.
 
-If an error occurs during evaluation, call error-thunk, passing it an
+If an error occurs during evaluation, call error-handler, passing it an
 error code describing the condition.  [Error codes are currently
 meaningless integers.  In the future, real values will be specified.]
-If this happens, the error-thunk is called outside the scope of the new
+If this happens, the error-handler is called outside the scope of the new
 root -- it is called in the same dynamic context in which
-with-new-thread was evaluated, but not in the callers thread.
+with-new-thread was evaluated, but not in the caller's thread.
 
 All the evaluation rules for dynamic roots apply to threads.
 @end deffn
@@ -287,53 +287,53 @@ blocked on @var{mutex} is awakened and grabs the mutex lock.
 @node Higher level thread procedures
 @subsection Higher level thread procedures
 
-@c NJFIXME the following doc is a repeat of the previous node!
+@c new by ttn, needs review
 
-@c begin (texi-doc-string "guile" "call-with-new-thread")
-@deffn primitive call-with-new-thread thunk error-thunk
-Evaluate @code{(thunk)} in a new thread, and new dynamic context,
-returning a new thread object representing the thread.
+Higher level thread procedures are available by loading the
+@code{(ice-9 threads)} module.  These provide standardized
+thread creation and mutex interaction.
 
-If an error occurs during evaluation, call error-thunk, passing it an
-error code describing the condition.  [Error codes are currently
-meaningless integers.  In the future, real values will be specified.]
-If this happens, the error-thunk is called outside the scope of the new
-root -- it is called in the same dynamic context in which
-with-new-thread was evaluated, but not in the callers thread.
+@c docstring begin (texi-doc-string "guile" "%thread-handler")
+@deffn primitive %thread-handler tag args@dots{}
 
-All the evaluation rules for dynamic roots apply to threads.
-@end deffn
+This procedure is specified as the standard error-handler for
+@code{make-thread} and @code{begin-thread}.  If the number of @var{args}
+is three or more, use @code{display-error}, otherwise display a message
+"uncaught throw to @var{tag}".  All output is sent to the port specified
+by @code{current-error-port}.
 
-@c begin (texi-doc-string "guile" "join-thread")
-@deffn primitive join-thread thread
-Suspend execution of the calling thread until the target @var{thread}
-terminates, unless the target @var{thread} has already terminated.
+Before display, global var @code{the-last-stack} is set to @code{#f}
+and signals are unmasked with @code{unmask-signals}.
+
+[FIXME: Why distinguish based on number of args?!  Cue voodoo music here.]
 @end deffn
 
-@c begin (texi-doc-string "guile" "yield")
-@deffn primitive yield
-If one or more threads are waiting to execute, calling yield forces an
-immediate context switch to one of them. Otherwise, yield has no effect.
+@c docstring begin (texi-doc-string "guile" "make-thread")
+@deffn macro make-thread fn [args@dots{}]
+Apply @var{fn} to @var{args} in a new thread formed by
+@code{call-with-new-thread} using @var{%thread-handler} as the error
+handler.
 @end deffn
 
-@c begin (texi-doc-string "guile" "make-mutex")
-@deffn primitive make-mutex
-Create a new mutex object.
+@c docstring begin (texi-doc-string "guile" "begin-thread")
+@deffn macro begin-thread first [rest@dots{}]
+Evaluate forms @var{first} and @var{rest} in a new thread formed by
+@code{call-with-new-thread} using @var{%thread-handler} as the error
+handler.
 @end deffn
 
-@c begin (texi-doc-string "guile" "lock-mutex")
-@deffn primitive lock-mutex mutex
-Lock @var{mutex}. If the mutex is already locked, the calling thread
-blocks until the mutex becomes available. The function returns when
-the calling thread owns the lock on @var{mutex}.
+@c docstring begin (texi-doc-string "guile" "with-mutex")
+@deffn macro with-mutex m [body@dots{}]
+Lock mutex @var{m}, evaluate @var{body}, and then unlock @var{m}.
+These sub-operations form the branches of a @var{dynamic-wind}.
 @end deffn
 
-@c docstring begin (texi-doc-string "guile" "unlock-mutex")
-@deffn primitive unlock-mutex mutex
-Unlocks @var{mutex} if the calling thread owns the lock on @var{mutex}.
-Calling unlock-mutex on a mutex not owned by the current thread results
-in undefined behaviour. Once a mutex has been unlocked, one thread
-blocked on @var{mutex} is awakened and grabs the mutex lock.
+@c docstring begin (texi-doc-string "guile" "monitor")
+@deffn macro monitor first [rest@dots{}]
+Evaluate forms @var{first} and @var{rest} under a newly created
+anonymous mutex, using @var{with-mutex}.
+
+[FIXME: Is there any way to access the mutex?]
 @end deffn