diff options
Diffstat (limited to 'docs/guide.md')
| -rw-r--r-- | docs/guide.md | 27 |
1 files changed, 23 insertions, 4 deletions
diff --git a/docs/guide.md b/docs/guide.md index ab30c3d..888e4ab 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -334,10 +334,29 @@ The loop never closes application file descriptors: delete the watch before closing its descriptor. Ready callbacks may add or remove watches. Do not call `yasl_loop_step()` or `yasl_loop_run()` recursively. -Cocoa dispatch waits for native events and checks the loop nonblockingly -afterward. An application FD alone does not currently wake an indefinite Cocoa -dispatch; use a bounded timeout when integrating such sources. `loop_kick()` -signals the loop pipe but is not a portable cross-thread event-posting API. +Every backend's dispatch wakes when a loop descriptor becomes ready. Cocoa +waits for native events and mirrors the loop's descriptors in a kqueue while it +waits. If kqueue rejects a descriptor, Cocoa bounds the wait to 10 ms instead. + +Two calls work from any thread. `yasl_loop_kick()` only wakes the loop, and it +is also safe in a signal handler. `yasl_loop_post()` queues a function to run +on the owning thread during a later step or dispatch. Use it to hand results +from worker threads to the loop: + +```c +static void results_ready(void *ud) +{ + worker_drain(ud); /* Runs on the loop thread. */ +} +/* On the worker thread; false means allocation failed. */ +yasl_loop_post(loop, results_ready, worker); +``` + +`yasl_loop_watch_signals()` delivers POSIX signals to a callback on the loop +thread. It installs a process-wide handler for each signal, with `SA_RESTART`, +and restores the previous action on unwatch. YASL leaves thread signal masks +alone: a watched signal must stay unblocked in at least one thread. Only one +loop can watch a given signal at a time. ## Native interoperability |