Repository: hannobraun/inotify-rs (language: rust)

Issue:
Document event deduplication
From the inotify man page:

> If  successive output inotify events produced on the inotify file descriptor are identical (same wd, mask, cookie, and name), then they are coalesced into a single event if the older event has not yet been read (but see BUGS). This reduces the amount of kernel memory required for the event queue, but also means that an application can't use inotify to reliably count file events.

This should be clearly documented in `Inotify::read_events`/`Inotify::read_events_blocking`.


Discussion / hints:

Fix patch:
diff --git a/src/lib.rs b/src/lib.rs
index c763578..a37f756 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -348,6 +348,8 @@ impl Inotify {
     /// This method will block the current thread until at least one event is
     /// available. If this is not desirable, please consider [`read_events`].
     ///
+    /// The documentation of [`read_events`] has additional about this call.
+    ///
     /// # Errors
     ///
     /// Directly returns the error from the call to [`read`], without adding any
@@ -372,14 +374,17 @@ impl Inotify {
     /// Returns any available events
     ///
     /// Returns an iterator over all events that are currently available. If no
-    /// events are available, an iterator is still returned.
+    /// events are available, an iterator is still returned. If you need a
+    /// method that will block until at least one event is available, please
+    /// consider [`read_events_blocking`].
+    ///
+    /// Please note that inotify will merge identical unread events into a
+    /// single event. This means this method can not be used to count the number
+    /// of file system events.
     ///
     /// The `buffer` argument, as the name indicates, is used as a buffer for
     /// the inotify events. Its contents may be overwritten.
     ///
-    /// If you need a method that will block until at least one event is
-    /// available, please consider [`read_events_blocking`].
-    ///
     /// # Errors
     ///
     /// This function directly returns all errors from the call to [`read`]. In


Test patch: