diff options
author | Marius Vollmer <mvo@zagadka.de> | 2002-10-07 16:34:28 +0000 |
---|---|---|
committer | Marius Vollmer <mvo@zagadka.de> | 2002-10-07 16:34:28 +0000 |
commit | b6506f45202f7e6baf584440d75ada581c050afc (patch) | |
tree | 8e69d9402d0e123e01cb2fa5291e598822495d6a | |
parent | 60aa332f83f373ec128d54e01ce89b68e86a5014 (diff) | |
download | guile-b6506f45202f7e6baf584440d75ada581c050afc.tar.gz |
* scheme-scheduling.texi (Asyncs): Updated.
* posix.texi (sigaction): Updated.
-rw-r--r-- | doc/ref/posix.texi | 27 | ||||
-rw-r--r-- | doc/ref/scheme-scheduling.texi | 119 |
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 |