summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMarius Vollmer <mvo@zagadka.de>2002-10-07 16:34:28 +0000
committerMarius Vollmer <mvo@zagadka.de>2002-10-07 16:34:28 +0000
commitb6506f45202f7e6baf584440d75ada581c050afc (patch)
tree8e69d9402d0e123e01cb2fa5291e598822495d6a
parent60aa332f83f373ec128d54e01ce89b68e86a5014 (diff)
downloadguile-b6506f45202f7e6baf584440d75ada581c050afc.tar.gz
* scheme-scheduling.texi (Asyncs): Updated.
* posix.texi (sigaction): Updated.
-rw-r--r--doc/ref/posix.texi27
-rw-r--r--doc/ref/scheme-scheduling.texi119
2 files changed, 84 insertions, 62 deletions
diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi
index 776f2485e..f372c6e48 100644
--- a/doc/ref/posix.texi
+++ b/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
-@var{signum}. @var{action} can be a Scheme procedure taking one
-argument, or the value of @code{SIG_DFL} (default action) or
+If @var{handler} is provided, it is installed as the new handler for
+@var{signum}. The parameter @var{handler} can be a Scheme procedure
+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
-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.
+was installed before @code{sigaction} was first used. When a scheme
+procedure has been specified, that procedure will run in the given
+@var{thread}. When no thread has been given, the thread that made this
+call to @code{sigaction} is used.
+
+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
diff --git a/doc/ref/scheme-scheduling.texi b/doc/ref/scheme-scheduling.texi
index ea060177a..01e35c1bb 100644
--- a/doc/ref/scheme-scheduling.texi
+++ b/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.
-* Asyncs:: Asynchronous procedure invocation.
-* Dynamic Roots:: Root frames of execution.
-* Threads:: Multiple threads of execution.
-* Fluids:: Thread-local variables.
+* Arbiters:: Synchronization primitives.
+* Asyncs:: Asynchronous procedure invocation.
+* Dynamic Roots:: Root frames of execution.
+* Threads:: Multiple threads of execution.
+* 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.
-Setting the mark on an async guarantees that the thunk will be executed
-somewhen in the future (@dfn{asynchronously}). Setting the mark more
-than once is satisfied by one execution of the thunk.
+Asyncs are a means of deferring the excution of Scheme code until it is
+safe to do so.
-Guile supports two types of asyncs: Normal asyncs and system asyncs.
-They differ in that marked system asyncs are executed implicitly as soon
-as possible, whereas normal asyncs have to be invoked explicitly.
-System asyncs are held in an internal data structure and are maintained
-by Guile.
+Guile provides two kinds of asyncs that share the basic concept but are
+otherwise quite different: system asyncs and user asyncs. System asyncs
+are integrated into the core of Guile and are executed automatically
+when the system is in a state to allow the execution of Scheme code.
+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
-@code{system-async}. They are marked with @code{async-mark} or
-@code{system-async-mark}, respectively.
+System asyncs can also be queued for threads other than the current one.
+This way, you can cause threads to asynchronously execute arbitrary
+code.
-@deffn {Scheme Procedure} async thunk
-@deffnx {C Function} scm_async (thunk)
-Create a new async for the procedure @var{thunk}.
-@end deffn
-
-@deffn {Scheme Procedure} system-async thunk
-@deffnx {C Function} scm_system_async (thunk)
-Create a new async for the procedure @var{thunk}. Also
-add it to the system's list of active async objects.
-@end deffn
+User asyncs offer a convenient means of queueing procedures for future
+execution and triggering this execution. They will not be executed
+automatically.
-@deffn {Scheme Procedure} async-mark a
-@deffnx {C Function} scm_async_mark (a)
-Mark the async @var{a} for future execution.
-@end deffn
-
-@deffn {Scheme Procedure} system-async-mark a
-@deffnx {C Function} scm_system_async_mark (a)
-Mark the async @var{a} for future execution.
-@end deffn
+@menu
+* System asyncs::
+* User asyncs::
+@end menu
-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}.
+@node System asyncs
+@subsection System 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
+To cause the future asynchronous execution of a procedure in a given
+thread, use @code{system-async-mark}.
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
-@c procedure for anyway?
+@node User asyncs
+@subsection User asyncs
+
+A user async is a pair of a thunk (a parameterless procedure) and a
+mark. Setting the mark on a user async will cause the thunk to be
+executed when the user async is passed to @code{run-asyncs}. Setting
+the mark more than once is satisfied by one execution of the thunk.
-@deffn {Scheme Procedure} noop . args
-@deffnx {C Function} scm_noop (args)
-Do nothing. When called without arguments, return @code{#f},
-otherwise return the first argument.
+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
@@ -259,8 +276,8 @@ When using Guile threads, keep in mind that each guile thread is
executed in a new dynamic root.
@menu
-* Low level thread primitives::
-* Higher level thread procedures::
+* Low level thread primitives::
+* Higher level thread procedures::
@end menu