summaryrefslogtreecommitdiff
path: root/doc/ref/api-scheduling.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2016-12-29 18:46:16 +0100
committerAndy Wingo <wingo@pobox.com>2016-12-29 18:46:16 +0100
commita0656ad4cf976b3845e9b9663a90b46b4cf9fc5a (patch)
tree22e621b5b32acb84fcbd82b1b7ff7d7f9e303740 /doc/ref/api-scheduling.texi
parent0ce8a9a5e01d3a12d83fea85968e1abb602c9298 (diff)
downloadguile-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.texi32
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,