guile/guile-core/doc scheme-scheduling.texi

[Thien-Thi Nguyen]

CVSROOT:        /cvs
Module name:    guile
Changes by:     Thien-Thi Nguyen <address@hidden>       01/04/06 02:52:45

Modified files:
        guile-core/doc : scheme-scheduling.texi 

Log message:
        (Higher level thread procedures): Rewrite.

CVSWeb URLs:
http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-core/doc/scheme-scheduling.texi.diff?r1=1.2&r2=1.3

Patches:
Index: guile/guile-core/doc/scheme-scheduling.texi
diff -u guile/guile-core/doc/scheme-scheduling.texi:1.2 
guile/guile-core/doc/scheme-scheduling.texi:1.3
--- guile/guile-core/doc/scheme-scheduling.texi:1.2     Tue Apr  3 06:11:14 2001
+++ guile/guile-core/doc/scheme-scheduling.texi Fri Apr  6 02:52:45 2001
@@ -225,16 +225,16 @@
 @c are in sync.
 
 @c begin (texi-doc-string "guile" "call-with-new-thread")
address@hidden primitive call-with-new-thread thunk error-thunk
address@hidden 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 @@
 @node Higher level thread procedures
 @subsection Higher level thread procedures
 
address@hidden NJFIXME the following doc is a repeat of the previous node!
address@hidden new by ttn, needs review
 
address@hidden begin (texi-doc-string "guile" "call-with-new-thread")
address@hidden 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
address@hidden(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.
address@hidden docstring begin (texi-doc-string "guile" "%thread-handler")
address@hidden primitive %thread-handler tag address@hidden
 
-All the evaluation rules for dynamic roots apply to threads.
address@hidden deffn
+This procedure is specified as the standard error-handler for
address@hidden 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}.
 
address@hidden begin (texi-doc-string "guile" "join-thread")
address@hidden 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
 
address@hidden begin (texi-doc-string "guile" "yield")
address@hidden 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.
address@hidden docstring begin (texi-doc-string "guile" "make-thread")
address@hidden macro make-thread fn address@hidden
+Apply @var{fn} to @var{args} in a new thread formed by
address@hidden using @var{%thread-handler} as the error
+handler.
 @end deffn
 
address@hidden begin (texi-doc-string "guile" "make-mutex")
address@hidden primitive make-mutex
-Create a new mutex object.
address@hidden docstring begin (texi-doc-string "guile" "begin-thread")
address@hidden macro begin-thread first address@hidden
+Evaluate forms @var{first} and @var{rest} in a new thread formed by
address@hidden using @var{%thread-handler} as the error
+handler.
 @end deffn
 
address@hidden begin (texi-doc-string "guile" "lock-mutex")
address@hidden 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}.
address@hidden docstring begin (texi-doc-string "guile" "with-mutex")
address@hidden macro with-mutex m address@hidden
+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
 
address@hidden docstring begin (texi-doc-string "guile" "unlock-mutex")
address@hidden 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.
address@hidden docstring begin (texi-doc-string "guile" "monitor")
address@hidden macro monitor first address@hidden
+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