* scheme-scheduling.texi (Asyncs): Updated.

* posix.texi (sigaction): Updated.

doc/ref/posix.texi

@@ -1443,7 +1443,7 @@ or user, as indicated by @var{which} and @var{who}. @var{which}
 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
 or @code{PRIO_USER}, and @var{who} is interpreted relative to
 @var{which} (a process identifier for @code{PRIO_PROCESS},
-process group identifier for @code{PRIO_PGRP}, and a user
+hhhhprocess group identifier for @code{PRIO_PGRP}, and a user
 identifier for @code{PRIO_USER}.  A zero value of @var{who}
 denotes the current process, process group, or user.
 @var{prio} is a value in the range -20 and 20, the default
@@ -1510,29 +1510,34 @@ Sends a specified signal @var{sig} to the current process, where
 @var{sig} is as described for the kill procedure.
 @end deffn
 
-@deffn {Scheme Procedure} sigaction signum [handler [flags]]
+@deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]]
 @deffnx {C Function} scm_sigaction (signum, handler, flags)
+@deffnx {C Function} scm_sigaction_for_thread (signum, handler, flags, thread)
 Install or report the signal handler for a specified signal.
 
 @var{signum} is the signal number, which can be specified using the value
 of variables such as @code{SIGINT}.
 
-If @var{action} is omitted, @code{sigaction} returns a pair: the
+If @var{handler} is omitted, @code{sigaction} returns a pair: the
 CAR is the current
 signal hander, which will be either an integer with the value @code{SIG_DFL}
 (default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which
 handles the signal, or @code{#f} if a non-Scheme procedure handles the
 signal.  The CDR contains the current @code{sigaction} flags for the handler.
 
-If @var{action} is provided, it is installed as the new handler for
+If @var{handler} is provided, it is installed as the new handler for
-@var{signum}.  @var{action} can be a Scheme procedure taking one
+@var{signum}.  The parameter @var{handler} can be a Scheme procedure
-argument, or the value of @code{SIG_DFL} (default action) or
+taking one argument, or the value of @code{SIG_DFL} (default action) or
 @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
-was installed before @code{sigaction} was first used.  Flags can
+was installed before @code{sigaction} was first used.  When a scheme
-optionally be specified for the new handler (@code{SA_RESTART} will
+procedure has been specified, that procedure will run in the given
-always be added if it's available and the system is using restartable
+@var{thread}.  When no thread has been given, the thread that made this
-system calls.)  The return value is a pair with information about the
+call to @code{sigaction} is used.
-old handler as described above.
+
+Flags can optionally be specified for the new handler (@code{SA_RESTART}
+will always be added if it's available and the system is using
+restartable system calls.)  The return value is a pair with information
+about the old handler as described above.
 
 This interface does not provide access to the "signal blocking"
 facility.  Maybe this is not needed, since the thread support may

doc/ref/scheme-scheduling.texi

@@ -7,11 +7,11 @@ plus the Cygnus programmer's manual; it should be *very* carefully
 reviewed and largely reorganized.]
 
 @menu
-* Arbiters::            Synchronization primitives.
+* Arbiters::                    Synchronization primitives.
-* Asyncs::              Asynchronous procedure invocation.
+* Asyncs::                      Asynchronous procedure invocation.
-* Dynamic Roots::       Root frames of execution.
+* Dynamic Roots::               Root frames of execution.
-* Threads::             Multiple threads of execution.
+* Threads::                     Multiple threads of execution.
-* Fluids::              Thread-local variables.
+* Fluids::                      Thread-local variables.
 @end menu
 
 
@@ -54,54 +54,40 @@ arbiter was locked. Otherwise, return @code{#f}.
 @section Asyncs
 
 @cindex asyncs
+@cindex user asyncs
 @cindex system asyncs
 
 @c FIXME::martin: Review me!
 
-An async is a pair of one thunk (a parameterless procedure) and a mark.
+Asyncs are a means of deferring the excution of Scheme code until it is
-Setting the mark on an async guarantees that the thunk will be executed
+safe to do so.
-somewhen in the future (@dfn{asynchronously}).  Setting the mark more
-than once is satisfied by one execution of the thunk.
 
-Guile supports two types of asyncs: Normal asyncs and system asyncs.
+Guile provides two kinds of asyncs that share the basic concept but are
-They differ in that marked system asyncs are executed implicitly as soon
+otherwise quite different: system asyncs and user asyncs.  System asyncs
-as possible, whereas normal asyncs have to be invoked explicitly.
+are integrated into the core of Guile and are executed automatically
-System asyncs are held in an internal data structure and are maintained
+when the system is in a state to allow the execution of Scheme code.
-by Guile.
+For example, it is not possible to execute Scheme code in a POSIX signal
+handler, but such a signal handler can queue a system async to be
+executed in the near future, when it is safe to do so.
 
-Normal asyncs are created with @code{async}, system asyncs with
+System asyncs can also be queued for threads other than the current one.
-@code{system-async}.  They are marked with @code{async-mark} or
+This way, you can cause threads to asynchronously execute arbitrary
-@code{system-async-mark}, respectively.
+code.
 
-@deffn {Scheme Procedure} async thunk
+User asyncs offer a convenient means of queueing procedures for future
-@deffnx {C Function} scm_async (thunk)
+execution and triggering this execution.  They will not be executed
-Create a new async for the procedure @var{thunk}.
+automatically.
-@end deffn
 
-@deffn {Scheme Procedure} system-async thunk
+@menu
-@deffnx {C Function} scm_system_async (thunk)
+* System asyncs::               
-Create a new async for the procedure @var{thunk}.  Also
+* User asyncs::                 
-add it to the system's list of active async objects.
+@end menu
-@end deffn
 
-@deffn {Scheme Procedure} async-mark a
+@node System asyncs
-@deffnx {C Function} scm_async_mark (a)
+@subsection System asyncs
-Mark the async @var{a} for future execution.
-@end deffn
 
-@deffn {Scheme Procedure} system-async-mark a
+To cause the future asynchronous execution of a procedure in a given
-@deffnx {C Function} scm_system_async_mark (a)
+thread, use @code{system-async-mark}.
-Mark the async @var{a} for future execution.
-@end deffn
-
-As already mentioned above, system asyncs are executed automatically.
-Normal asyncs have to be explicitly invoked by storing one or more of
-them into a list and passing them to @code{run-asyncs}.
-
-@deffn {Scheme Procedure} run-asyncs list_of_a
-@deffnx {C Function} scm_run_asyncs (list_of_a)
-Execute all thunks from the asyncs of the list @var{list_of_a}.
-@end deffn
 
 Automatic invocation of system asyncs can be temporarily disabled by
 calling @code{mask-signals} and @code{unmask-signals}.  Setting the mark
@@ -110,6 +96,20 @@ run once execution is enabled again.  Please note that calls to these
 procedures should always be paired, and they must not be nested, e.g. no
 @code{mask-signals} is allowed if another one is still active.
 
+@deffn {Scheme procedure} system-async-mark proc [thread]
+@deffnx {C Function} scm_system_async_mark (proc)
+@deffnx {C Function} scm_system_async_mark_for_thread (proc, thread)
+Mark @var{proc} (a procedure with zero arguments) for future execution
+in @var{thread}.  When @var{proc} has already been marked for
+@var{thread} but has not been executed yet, this call has no effect.
+When @var{thread} is omitted, the thread that called
+@code{system-async-mark} is used.
+
+This procedure is not safe to be called from signal handlers.  Use
+@code{scm_sigaction} or @code{scm_sigaction_for_thread} to install
+signal handlers.
+@end deffn
+
 @deffn {Scheme Procedure} mask-signals
 @deffnx {C Function} scm_mask_signals ()
 Mask signals. The returned value is not specified.
@@ -120,13 +120,30 @@ Mask signals. The returned value is not specified.
 Unmask signals. The returned value is not specified.
 @end deffn
 
-@c FIXME::martin: Find an example for usage of `noop'.  What is that
+@node User asyncs
-@c procedure for anyway?
+@subsection User asyncs
 
-@deffn {Scheme Procedure} noop . args
+A user async is a pair of a thunk (a parameterless procedure) and a
-@deffnx {C Function} scm_noop (args)
+mark.  Setting the mark on a user async will cause the thunk to be
-Do nothing.  When called without arguments, return @code{#f},
+executed when the user async is passed to @code{run-asyncs}.  Setting
-otherwise return the first argument.
+the mark more than once is satisfied by one execution of the thunk.
+
+User asyncs are created with @code{async}.  They are marked with
+@code{async-mark}.
+
+@deffn {Scheme Procedure} async thunk
+@deffnx {C Function} scm_async (thunk)
+Create a new user async for the procedure @var{thunk}.
+@end deffn
+
+@deffn {Scheme Procedure} async-mark a
+@deffnx {C Function} scm_async_mark (a)
+Mark the user async @var{a} for future execution.
+@end deffn
+
+@deffn {Scheme Procedure} run-asyncs list_of_a
+@deffnx {C Function} scm_run_asyncs (list_of_a)
+Execute all thunks from the marked asyncs of the list @var{list_of_a}.
 @end deffn