file system watching support

[Guest0x0]

This PR adds file system watching support for moonbitlang/async/fs. The goal is to provide API with consistent behavior & simple interface on all platforms. To achieve this goal, some hard works are done internally to uniting the platform differences between the underlying OS primitives, performing rename detection, etc. Under the hood, inotify is used on Linux, kqueue with EVFILT_VNODE is used on MacOS, and ReadDirectoryChangesW is used on Windows.

Currently only recursive directory watching is supported. Shallow directory watching may be added in the future, while single file watching seems difficult on Windows.

For behavior details, see the document for @fs.FsEvent and @fs.Watcher::Watcher. Some feature highlights:

• uniform behavior across platforms: output of tests are exactly the same on all three platforms
• best-effort rename detection: rename operation within the whole watched directory is detected with high probability on all platforms.
• best-effort overflow avoidance: both inotify and ReadDirectoryChangesW may overflow when there are too many events. Here @fs.Watcher try to avoid such overflow by:
  • maintain a separated task to handle OS events, so that even if the even if the user does not retrieve events from the watcher, OS events are still processed as soon as possible to avoid kernel buffer overflow
  • perform directory rescan when overflow really happens, so that at least Create/Remove/Rename operations are properly reported, and the file hierarchy of the watched tree can be properly rebuilt. The user will still receive a Overflow event in this case, indicating that the content of all watched files may have changed

[coveralls]

Coverage Report for CI Build 244

Coverage decreased (-1.5%) to 77.055%

Details

• Coverage decreased (-1.5%) from the base build.
• Patch coverage: 148 uncovered changes across 6 files (239 of 387 lines covered, 61.76%).
• 1 coverage regression across 1 file.

Uncovered Changes

File	Changed	Covered	%
src/fs/watch_kqueue.mbt	108	0	0.0%
src/fs/watch_inotify.mbt	128	109	85.16%
src/fs/watch_windows.mbt	124	111	89.52%
src/internal/event_loop/fs.mbt	17	13	76.47%
src/fs/watch_unix.mbt	6	4	66.67%
src/os_error/error.mbt	2	0	0.0%

Coverage Regressions

1 previously-covered line in 1 file lost coverage.

File	Lines Losing Coverage	Coverage
src/internal/gzip_internal/decoder.mbt	1	87.98%

---

Coverage Stats

Relevant Lines:	4428
Covered Lines:	3412
Line Coverage:	77.06%
Coverage Strength:	56284.95 hits per line

---

💛 - Coveralls