From: Ian Jackson Date: Sun, 21 Sep 2014 14:02:40 +0000 (+0100) Subject: poll: Document reentrancy restriction on before() X-Git-Tag: base.ipv6-polypath-fixes-2.v1~70 X-Git-Url: https://git.distorted.org.uk/~mdw/secnet/commitdiff_plain/51abbe5f68f3c784987bc5f5d9575c967ec5895d?hp=8bebb29950d2a3c8558e676575cbff35b4e360c3 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.) Also, document a couple of features of the afterpoll_fn interface. Signed-off-by: Ian Jackson --- diff --git a/secnet.h b/secnet.h index b5028bb..2c55a32 100644 --- a/secnet.h +++ b/secnet.h @@ -198,10 +198,20 @@ 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); + /* If beforepoll_fn returned ERANGE, afterpoll_fn gets nfds==0. + afterpoll_fn never gets !!(fds[].revents & POLLNVAL) - such + a report is detected as a fatal error by the event loop. */ /* void BEFOREPOLL_WANT_FDS(int want); * Expects: int *nfds_io;