Monitors

fswatch acts as a front-end to system-specific monitors. Currently, the available monitors are:

• The FSEvents monitor, a monitor based on the File System Events API of Apple OS X.
• The kqueue monitor, a monitor based on kqueue, an event notification interface introduced in FreeBSD 4.1 and supported on most *BSD systems (including OS X).
• The inotify monitor, a Linux kernel subsystem that reports file system changes to applications.
• The poll monitor, a monitor which periodically stats the file system, saves file modification times in memory and manually calculates file system changes, which can work on any operating system where stat (2) can be used.

Each monitor has its own strengths, weakness and peculiarities. Although fswatch strives to provide a uniform experience no matter which monitor is used, it is still important for users to know which monitor they are using and to be aware of existing bugs, limitations, corner cases or pathological behaviour.

The FSEvents Monitor

The FSEvents monitor, available only on Apple OS X, has no known limitations and scales very well with the number of files being observed. In fact, I observed no performance degradation when testing fswatch observing changes on a filesystem of 500 GB over long periods of time. On OS X, this is the default monitor.

The kqueue Monitor

The kqueue monitor, available on any *BSD system featuring kqueue, requires a file descriptor to be opened for every file being watched. As a result, this monitor scales badly with the number of files being observed and may begin to misbehave as soon as the fswatch process runs out of file descriptors. In this case, fswatch dumps one error on standard error for every file that cannot be opened. Beware that on some systems the maximum number of file descriptors that can be opened by a process is set to a very low value (values as low as 256 are not uncommon), even if the operating system may allow a much larger value.

If you are running out of file descriptors when using this monitor and you cannot reduce the number of observed items, either:

• Consider raising the number of maximum open file descriptors (check your OS documentation).
• Consider using another monitor.

The inotify Monitor

The inotify monitor, available on Linux since kernel 2.6.13, may suffer a queue overflow if events are generated faster than they are read from the queue. In any case, the application is guaranteed to receive an overflow notification which can be handled to gracefully recover. fswatch currently throws an exception if a queue overflow occurs. Future versions will handle the overflow by emitting proper notifications. However, the odds of observing a queue overflow on a default configured mainstream GNU/Linux distribution is very low.

The inotify API sends events for the direct child elements of a watched directory and it scales pretty well with the number of watched items. For this reason, depending on the number of files to watch, it may sometimes be preferable to watch a common parent directory and filter received events rather than adding a huge number of file watches.

The Poll Monitor

The poll monitor was added as a fallback mechanisms in the cases where no other monitor could be used, including:

• Operating system without any sort of file events API.
• Situations where the limitations of the available monitors cannot be overcome (i.e.: observing a number of files greater than the available file descriptors on a system using the kqueue monitor).

The poll monitor, available on any platform, only relies on available CPU and memory to perform its task (besides the stat() function). The performance of this monitor degrades linearly with the number of files being watched.

The authors' experience indicates that fswatch requires approximately 150 MB or RAM memory to observe a hierarchy of 500.000 files with a minimum path length of 32 characters. A common bottleneck of the poll monitor is disk access, since stat()-ing a great number of files may take a huge amount of time. In this case, the latency should be set to a sufficiently large value in order to reduce the performance degradation that may result from frequent disk access.