diff options
author | Andy Wingo <wingo@pobox.com> | 2016-12-29 18:46:16 +0100 |
---|---|---|
committer | Andy Wingo <wingo@pobox.com> | 2016-12-29 18:46:16 +0100 |
commit | a0656ad4cf976b3845e9b9663a90b46b4cf9fc5a (patch) | |
tree | 22e621b5b32acb84fcbd82b1b7ff7d7f9e303740 /doc/ref/api-scheduling.texi | |
parent | 0ce8a9a5e01d3a12d83fea85968e1abb602c9298 (diff) | |
download | guile-a0656ad4cf976b3845e9b9663a90b46b4cf9fc5a.tar.gz |
New interfaces to help wait on fd/cond
* libguile/async.h:
* libguile/async.c (struct scm_thread_wake_data): Include the cond to
signal. Be a union and include a tag.
(scm_i_prepare_to_wait): Rename from scm_i_setup_sleep and take wake
data directly. Also call scm_i_wait_finished as appropriate.
(scm_i_wait_finished): Rename from scm_i_reset_sleep.
(scm_i_prepare_to_wait_on_fd, scm_c_prepare_to_wait_on_fd):
(scm_i_prepare_to_wait_on_cond, scm_c_prepare_to_wait_on_cond): New
functions.
(scm_c_wait_finished): New function.
(scm_system_async_mark_for_thread): Adapt to wake data change.
* libguile/threads.c (block_self, scm_std_select): Adapt to async
interface changes.
* doc/ref/api-scheduling.texi (Asyncs): Doc new public interfaces.
Diffstat (limited to 'doc/ref/api-scheduling.texi')
-rw-r--r-- | doc/ref/api-scheduling.texi | 32 |
1 files changed, 32 insertions, 0 deletions
diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi index 86a1ad27c..bf85a6411 100644 --- a/doc/ref/api-scheduling.texi +++ b/doc/ref/api-scheduling.texi @@ -306,6 +306,38 @@ one level. This function must be used inside a pair of calls to Wind}). @end deftypefn +Sometimes you want to interrupt a thread that might be waiting for +something to happen, for example on a file descriptor or a condition +variable. In that case you can inform Guile of how to interrupt that +wait using the following procedures: + +@deftypefn {C Function} int scm_c_prepare_to_wait_on_fd (int fd) +Inform Guile that the current thread is about to sleep, and that if an +asynchronous interrupt is signalled on this thread, Guile should wake up +the thread by writing a zero byte to @var{fd}. Returns zero if the +prepare succeeded, or nonzero if the thread already has a pending async +and that it should avoid waiting. +@end deftypefn + +@deftypefn {C Function} int scm_c_prepare_to_wait_on_cond (scm_i_pthread_mutex_t *mutex, scm_i_pthread_cond_t *cond) +Inform Guile that the current thread is about to sleep, and that if an +asynchronous interrupt is signalled on this thread, Guile should wake up +the thread by acquiring @var{mutex} and signalling @var{cond}. The +caller must already hold @var{mutex} and only drop it as part of the +@code{pthread_cond_wait} call. Returns zero if the prepare succeeded, +or nonzero if the thread already has a pending async and that it should +avoid waiting. +@end deftypefn + +@deftypefn {C Function} void scm_c_wait_finished (void) +Inform Guile that the current thread has finished waiting, and that +asynchronous interrupts no longer need any special wakeup action; the +current thread will periodically poll its internal queue instead. +@end deftypefn + +Guile's own interface to @code{sleep}, @code{wait-condition-variable}, +@code{select}, and so on all call the above routines as appropriate. + Finally, note that threads can also be interrupted via POSIX signals. @xref{Signals}. As an implementation detail, signal handlers will effectively call @code{system-async-mark} in a signal-safe way, |