work around epoll spurious notifications

1 files changed, 7 insertions, 4 deletions

diff --git a/ev.pod b/ev.pod
index b0cfaf5..b4e416f 100644
--- a/ev.pod
+++ b/ev.pod
@@ -391,16 +391,19 @@ of shortcomings, such as silently dropping events in some hard-to-detect
 cases and requiring a system call per fd change, no fork support and bad
 support for dup.
 
+Epoll is also notoriously buggy - embedding epoll fds should work, but
+of course doesn't, and epoll just loves to report events for totally
+I<different> file descriptors (even already closed ones) than registered
+in the set (especially on SMP systems). Libev tries to counter these
+spurious notifications by employing an additional generation counter and
+comparing that against the events to filter out spurious ones.
+
 While stopping, setting and starting an I/O watcher in the same iteration
 will result in some caching, there is still a system call per such incident
 (because the fd could point to a different file description now), so its
 best to avoid that. Also, C<dup ()>'ed file descriptors might not work
 very well if you register events for both fds.
 
-Please note that epoll sometimes generates spurious notifications, so you
-need to use non-blocking I/O or other means to avoid blocking when no data
-(or space) is available.
-
 Best performance from this backend is achieved by not unregistering all
 watchers for a file descriptor until it has been closed, if possible,
 i.e. keep at least one watcher active per fd at all times. Stopping and