support reporting events for file system watcher

[Guest0x0]

This PR add a new method .wait() for @fs.Watcher, which is similar to previous .wait_any(), but return a list of events describing changes on the file system since the last query.

Two new options are added to @fs.Watcher(..) to control event reporting behavior of .wait():

• When a directory is created/moved inside watched tree or removed/moved outside watched tree:

  • if report_child_event=true, respective create/remove events will be emitted for everything inside that directory. This mode is useful if tracking the exact list of files in desirable.
  • If report_child_event=false (the default), only a single event for the directory itself will be emitted, making the watcher less noisy

  Note that if a rename event is emitted for a directory, events will be reported for changes since the last query for the renamed directory. regardless of the value of report_child_event.

• If report_event_on_init=true (false by default), the first wait call will return immediately after watcher creation, reporting events describing the initial structure of the watched directory. This is useful for keeping the knowledge of the caller in sync with the watcher. Note that you probably want to set report_child_event=true as well in this case.

wait performs rename detection based on the physical ID of files. The rule is:

• renaming for regular files are detected globally for the whole watched tree
• renaming for directory are only detected locally within the same parent directory. Directory renaming across directory are treated as separated remove + create events.
• if the destination of a rename already contains something, a remove event will be emitted for the old file on the destination.
  When the watcher cannot serialize the file system changes into simple rename events, for example two files are atomically swapped, a remove event on the old path + a create event on the new path will be created.

[coveralls]

Coverage Report for CI Build 806

Coverage increased (+0.08%) to 77.283%

Details

• Coverage increased (+0.08%) from the base build.
• Patch coverage: 13 uncovered changes across 1 file (64 of 77 lines covered, 83.12%).
• No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
src/fs/watch.mbt	77	64	83.12%

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	4763
Covered Lines:	3681
Line Coverage:	77.28%
Coverage Strength:	11860.41 hits per line

---

💛 - Coveralls