windows-file-watcher
Memory-safe Windows path-change watching over ReadDirectoryChangesW, with a
FindFirstChangeNotification coarse fallback for filesystems that do not
support the detailed API.
This crate is Windows-only: every item is gated behind cfg(windows), so it
resolves to an empty crate on other targets. Platform-independent watching is
meant to be built at a higher layer -- this crate is about excellent Windows
behaviour (path-name and notification-limitation fidelity) with memory safety.
The model
A [Monitor] owns the watching and runs on no threads of its own -- all work
runs on windows-threadpool-sys's thread pool. It hands out [Session]s, each
of which bundles a way to make requests with the destination every subscription
made through it delivers to; [Monitor::session] returns one together with the
[Receiver] its notifications arrive on. [Session::subscribe] registers a
path and returns an affine [Watch] that cancels when dropped, and
[Session::answer] responds to an interactive subscription's retry question.
use ;
let monitor = new?;
let = monitor.session;
let watch = session.subscribe?;
while let Some = receiver.recv
# drop;
# Ok::
A subscription targets either a directory (optionally recursive) or a single file, watched through its parent directory. Several subscriptions on the same directory share one coalesced watcher and one kernel read.
Everything is queued, in both directions
The crate never calls into client code. A request is something the client enqueues; a notification is something the crate enqueues and the client collects. Nothing a client does -- blocking, panicking, being slow -- can stall or unwind the crate's own cadence, and that holds by construction rather than by asking a callback to behave.
Which thread a client drains on is entirely its own business. A client that
does not want to dedicate one to [Receiver::recv] can take
[Receiver::doorbell] and wait on it from its own thread pool -- including from
a ThreadpoolWait callback: ringing a doorbell is crate-owned queue signaling,
a bounded, non-blocking event, not a callback carrying client data, so this is
not an exception to "the crate never calls into client code" -- there is no
exception.
Losses are reported, never silent
ReadDirectoryChangesW can lose changes -- its buffer overflows under a burst
-- and so can a client that stops draining, or a fault outage the monitor is
still recovering from. Every hole is reported as one cause-tagged
[Notification::Desync] meaning re-scan. Honest reporting of that limitation
is a core requirement of this crate rather than an afterthought.
Faults recover on their own, or on your terms
A directory that cannot be opened yet, or a live watch that faults, is never a terminal state: the monitor retries indefinitely (a target that will never become watchable is the one exception, reported permanently rather than retried forever). Each subscription chooses, at registration, how that recovery is timed:
RetryMode::Defaults(the default): the monitor retries autonomously, at a fixed 500ms delay per attempt.RetryMode::Interactive: on fault, the monitor asks -- aNotification::RetryQuestionnames the failing operation and carries the realFaultDetailbehind it, and [Session::answer] supplies the next delay (clamped to a 50ms floor); an explicitanswer(watch, None)declines, which is what counts at the default -- never answering at all leaves the question outstanding indefinitely. A directory shared by several subscriptions takes the earliest answer.
A subscription that opts into WatchOptions::report_liveness additionally
receives Suspended/Resumed brackets around an outage and an
Established { mode } report naming which tier (detailed or coarse) is
actually watching.
Two tiers, chosen automatically
Not every filesystem supports ReadDirectoryChangesW. When it does not, the
monitor falls back to the coarse FindFirstChangeNotification family, which
reports only that something changed within reach, delivered as
Desync { Coarse }. Which tier a directory uses is re-resolved on every
establish and re-establish, so a recovered fault always retries the detailed
path first.
What this crate is not
It does not verify a reported change by re-reading content, does not cache
per-volume capability across process restarts, and does not surface the
extended ReadDirectoryChangesExW record format. These are recorded,
deliberate v1 scope decisions (see DESIGN-NOTES.md), not
oversights.
Testing your own code
Building on this crate? The off-by-default test-util feature lets you drive
your notification-handling code with synthetic notifications through a real
Receiver you construct yourself -- no filesystem, no thread pool, and
deterministic because your test is the source of every event. See
TESTING.md for the full guide, and
examples/test_your_handler.rs for a worked
example.
Stress-testing tool
src/bin/run_scenario.rs replays a persisted JSON scenario file through the
same data-driven stress model the test suite uses; see
src/bin/README.md for usage and examples. It is
gated behind the scenario-tool feature (serde/serde_json are optional
dependencies), so it never affects an ordinary build of this crate.
License
MIT. Copyright (c) Mike Grier.