poll: Document reentrancy restriction on before()

If the before() callback might modify the wanted fds or timeouts of
other poll users, the loop over poll users in run() might produce
wrong answers.

Therefore, document that this is not permitted.  (All of the existing
before() implementations are indeed fine.)

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/secnet.h b/secnet.h
index 62f27d5b238229482e789dfcd2461e5ea4ef335e..0537e39cdc4a3b8c807be43e48fbae127bc18955 100644 (file)
--- a/secnet.h
+++ b/secnet.h
@@ -198,7 +198,14 @@ int32_t calculate_max_start_pad(void);
 
 /* If nfds_io is insufficient for your needs, set it to the required
    number and return ERANGE. timeout is in milliseconds; if it is too
-   high then lower it. It starts at -1 (==infinite) */
+   high then lower it. It starts at -1 (==infinite). */
+/* Note that beforepoll_fn may NOT do anything which might change the
+   fds or timeouts wanted by other registered poll loop loopers.
+   Callers should make sure of this by not making any calls into other
+   modules from the beforepoll_fn; the easiest way to ensure this is
+   for beforepoll_fn to only retreive information and not take any
+   action.
+ */
 typedef int beforepoll_fn(void *st, struct pollfd *fds, int *nfds_io,
                          int *timeout_io);
 typedef void afterpoll_fn(void *st, struct pollfd *fds, int nfds);