Look into inotify gotchas and what can be done about them

[hannobraun]

From Stack Overflow:

The library does nothing to highlight major gotchas of inotify: event queue overflows, IN_IGNORED and hard links sharing the same inode (and the same inotify watch descriptors!)

It's true that inotify has major gotchas that make it hard to use. Since inotify-rs is intended to be a low-level wrapper, to be used as a building block for higher-level libraries, I'm not sure whether all of those can be reasonably handled in this library.

However, I think it's a good idea to look into each of the issues mentioned in the above quote (and possibly other issues mentioned in the man pages) and either
a) find a way to reasonably handle them within inotify-rs, or
b) clearly document that they exist and are not handled by inotify-rs.

[hannobraun]

I've reviewed the concerns listed in the quote from the issue description

event queue overflows

There's an idea on how to make those more explicit in #76.

IN_IGNORED

I'm not sure what exactly the original poster meant by that, but I believe it could be made more explicit. Right now it's just another type of event.

I've added a note to that effect to #76.

hard links sharing the same inode (and the same inotify watch descriptors!)

I don't think we can do anything about that within the scope of this library. In any case, the issue is clearly documented in the API reference (Inotify::add_watch).

In addition, I've reviewed the inotify man page and found the following:

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 behavior should be documented. I've opened #94.

Since everything mentioned in this issue either has been handled or is being tracked in other issues, I'm closing this one.