From 30005837f3f2a28b7e6538182f003f78a0fef223 Mon Sep 17 00:00:00 2001 From: Albert Chu Date: Wed, 25 Sep 2024 09:55:13 -0700 Subject: [PATCH] libsubprocess: add fbuf watcher details Problem: Comments on the fbuf read and write watcher are a little thin. Add some additional comments to remind readers what the watchers do. --- src/common/libsubprocess/fbuf_watcher.h | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/src/common/libsubprocess/fbuf_watcher.h b/src/common/libsubprocess/fbuf_watcher.h index 9ddf53e0c9ea..3463a5727fc9 100644 --- a/src/common/libsubprocess/fbuf_watcher.h +++ b/src/common/libsubprocess/fbuf_watcher.h @@ -18,8 +18,15 @@ enum { FBUF_WATCHER_LINE_BUFFER = 1, /* line buffer data before invoking callback */ }; -/* on eof, callback will be called with an empty buffer */ -/* if line buffered, second to last callback may not contain a full line */ +/* read watcher + * + * - data from fd copied into buffer + * - when data is available, triggers callback + * - on eof, callback will be called with an empty buffer + * - if line buffered, second to last callback may not contain a full line + * - users should read from the buffer or stop the watcher, to avoid + * excessive event loop iterations without progress + */ flux_watcher_t *fbuf_read_watcher_create (flux_reactor_t *r, int fd, int size, @@ -40,7 +47,11 @@ const char *fbuf_read_watcher_get_data (flux_watcher_t *w, int *lenp); void fbuf_read_watcher_incref (flux_watcher_t *w); void fbuf_read_watcher_decref (flux_watcher_t *w); -/* 'cb' only called after fd closed (FLUX_POLLOUT) or error (FLUX_POLLERR) */ +/* write watcher + * + * - data from buffer written to fd + * - callback triggered after fd closed (FLUX_POLLOUT) or error (FLUX_POLLERR) + */ flux_watcher_t *fbuf_write_watcher_create (flux_reactor_t *r, int fd, int size,