@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
@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 proc [args@dots{}]
+Apply @var{proc} to @var{args} in a new thread formed by
+@code{call-with-new-thread} using @code{%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 @code{%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 @code{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 @code{with-mutex}.
+
+[FIXME: Is there any way to access the mutex?]
@end deffn
HCoop / bpt / guile.git / blobdiff