inotify rant

// Welcome to the inotify API to avoid polling your filesystem for changes!
//
// For each inode you add to your inotify instance you get a `watch descriptor'
// to identify it.  You cannot supply your own pointer-sized user data like you
// can with any sane callback mechanism, so you'll have to keep your own lookup
// table indexed by watch descriptor.
//
// Fortunately, watch descriptors are integers allocated sequentially from 1
// upwards so you can use a simple array.... provided of course you weren't
// hoping to be able to dynamically add and remove watches since -- unlike file
// descriptors -- watch descriptors are never reused, so you'll need a sparse
// array to avoid leaking memory.
//
// Also, you can't add an inode more than once (even via different paths), so
// if different things request events for, what turns out to be, the same inode
// you will have to notice this and demultiplex the events yourself,
//
// Also, after a sufficient number of dynamic changes to the watch list you
// will run out of watch descriptors, get ENOSPC, and need to rebuild
// everything on a fresh inotify instance.  To keep things interesting, the
// same error code is used to indicate you've hit the configured maximum number
// of total watches per user, which is obviously not fixed by rebuilding (but
// may be transient, unlike running out of descriptors).
//
// Luckily, the code to rescan all your watches needed to be written anyway to
// deal with the case where the kernel indicates the event queue overflowed and
// events were dropped.
//
// Oh, and if for some reason you'd wish to support kernel versions older than
// 2.6.36 and therefore can't use IN_EXCL_UNLINK, if any child of a watched dir
// is unlinked you'll probably want to remove, readd, and rescan the directory
// since otherwise you will still get events for the unlinked child but have no
// way of distinguishing these from events for a new child with the same name.
//
// Of course it's also quite possible you can't create the inotify instance at
// all since you hit the per-user limit on inotify instances (128 by default).
//
// Any questions?  Have fun!