windows_file_watcher/monitor.rs
1// Copyright (c) 2026 Mike Grier
2//! The monitor: the crate's single servicing authority and the owner of every
3//! per-directory watcher.
4//!
5//! A `Monitor` is created once and lives as long as the watching does. It owns no
6//! threads (D-3): its servicing runs on a [`Servicer`], which is one
7//! `ThreadpoolWork` draining the request queue, and its watchers run on the
8//! pool's I/O completions. Client interaction is entirely queued in both
9//! directions -- requests in, notifications out -- so the crate never calls into
10//! client code on its cadence path (D-2).
11//!
12//! # Teardown blocks
13//!
14//! [`Monitor::shut_down`] closes the servicing path *before* tearing down
15//! watchers, which is the ordering D-23 and D-34 exist to enforce: with the queue
16//! still open a drain could adopt a watcher after teardown had already walked the
17//! table, leaving an armed read behind that nothing would ever cancel. `Drop`
18//! delegates to it, so a monitor that goes out of scope blocks until every read is
19//! cancelled and every callback has finished (D-20).
20
21use std::collections::HashMap;
22use std::io;
23use std::num::NonZeroUsize;
24use std::path::PathBuf;
25use std::sync::atomic::{AtomicU64, Ordering};
26use std::sync::{Arc, Mutex, OnceLock, Weak};
27use std::time::Duration;
28
29use wtf_string::Wtf16String;
30
31use windows_sys::Win32::Foundation::ERROR_DIRECTORY;
32use windows_threadpool_sys::timer::ThreadpoolTimer;
33
34use crate::directory::{DirectoryHandle, DirectoryId, FaultDetail, OpenFailure, classify_detail};
35use crate::queue::{
36 DEFAULT_BOUND, Notification, Outcome, Receiver, Reservation, Sender, StandingSlot, WatchId,
37 channel_with_bound,
38};
39use crate::retry::{FaultOperation, clamp};
40use crate::route::{Route, RouteScope};
41use crate::servicing::{Rejected, Servicer};
42use crate::session::Session;
43use crate::watch::{RetryMode, VolumeChangeDecision, WatchOptions};
44use crate::watcher::DirectoryWatcher;
45
46/// A message on the monitor's request queue.
47///
48/// Every variant is serviced by the single drain, so the resident state they
49/// mutate needs no further synchronisation of its own (D-2).
50///
51/// Crate-internal: a client reaches this through [`Session::subscribe`] and
52/// [`Watch::cancel`](crate::watch::Watch::cancel), which is what guarantees the
53/// completion slot a request carries was reserved before it was submitted
54/// (D-33). A publicly constructible request could not make that promise.
55pub(crate) enum Request {
56 /// Begin watching a path on behalf of one subscription.
57 Subscribe {
58 /// The identifier every notification from this subscription carries.
59 watch: WatchId,
60 /// The directory to watch. M4 resolves a file target to its parent.
61 path: PathBuf,
62 /// What the client stated at registration.
63 options: WatchOptions,
64 /// The session sink this subscription delivers to (D-11).
65 sink: Sender,
66 /// The slot this request's completion will occupy, taken before the
67 /// request was submitted so delivering it cannot fail (D-33).
68 completion: Reservation,
69 /// The standing fault-question reservation (D-27/D-28), present iff
70 /// this subscription can ever need one (`retry == Interactive` or
71 /// `on_volume_change == Confirm`). `report_liveness` alone never
72 /// creates one: `Suspended`/`Resumed`/`Established` use best-effort
73 /// sends and reserve nothing.
74 fault_slot: Option<StandingSlot>,
75 },
76 /// Stop watching, and release the watcher.
77 Cancel {
78 /// The subscription to end.
79 watch: WatchId,
80 /// As for `Subscribe`, but reserved at *registration* rather than at
81 /// cancellation: `Drop` has no way to report a refused reservation, so
82 /// the room for a cancellation completion is held for the whole life of
83 /// the subscription.
84 completion: Reservation,
85 },
86 /// Internal: re-attempt establishing a still-pending subscription, after
87 /// its retry timer fired (M5.1). Never constructed by a client -- only
88 /// [`Subscription::Pending`]'s own retry timer submits this.
89 Retry {
90 /// The subscription to retry.
91 watch: WatchId,
92 },
93 /// A client's answer to an interactive subscription's fault question
94 /// (D-27/M5.3), submitted through
95 /// [`Session::answer`](crate::session::Session::answer). Not itself a
96 /// request with a lifecycle, so it carries no completion; it is simply
97 /// ignored if `watch` is not currently awaiting an answer.
98 Answer {
99 /// The subscription answering.
100 watch: WatchId,
101 /// The next retry delay, or `None` to decline (counted at the failing
102 /// operation's default).
103 delay: Option<Duration>,
104 },
105 /// A client's answer to a volume-change question (D-78/M12), submitted
106 /// through
107 /// [`Session::answer_volume_change`](crate::session::Session::answer_volume_change).
108 /// Carries no completion, for the same reason `Answer` does not; ignored
109 /// if `watch` is not currently awaiting one.
110 AnswerVolumeChange {
111 /// The subscription answering.
112 watch: WatchId,
113 /// Whether to keep this subscription running against the new volume.
114 decision: VolumeChangeDecision,
115 },
116}
117
118impl std::fmt::Debug for Request {
119 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
120 match self {
121 Request::Subscribe {
122 watch,
123 path,
124 options,
125 ..
126 } => f
127 .debug_struct("Subscribe")
128 .field("watch", watch)
129 .field("path", path)
130 .field("options", options)
131 .finish_non_exhaustive(),
132 Request::Cancel { watch, .. } => f
133 .debug_struct("Cancel")
134 .field("watch", watch)
135 .finish_non_exhaustive(),
136 Request::Retry { watch } => f.debug_struct("Retry").field("watch", watch).finish(),
137 Request::Answer { watch, delay } => f
138 .debug_struct("Answer")
139 .field("watch", watch)
140 .field("delay", delay)
141 .finish(),
142 Request::AnswerVolumeChange { watch, decision } => f
143 .debug_struct("AnswerVolumeChange")
144 .field("watch", watch)
145 .field("decision", decision)
146 .finish(),
147 }
148 }
149}
150
151/// One live subscription's resident state.
152enum Subscription {
153 /// Registered, but nothing could be opened yet for a *retryable* reason
154 /// (D-22); a retry timer is always running while in this state (M5.1).
155 Pending {
156 /// The path as the client named it. Re-attempted from here every
157 /// retry, since which of `path` and its parent is opened (D-7) can
158 /// change once something actually exists there.
159 path: PathBuf,
160 options: WatchOptions,
161 /// This subscription's session sink (D-11), kept so a later successful
162 /// establishment (M5.1) or a permanent failure discovered on a retry
163 /// has somewhere to deliver.
164 sink: Sender,
165 /// Fires the next `Request::Retry`. Created once at registration and
166 /// re-armed (never recreated) across however many attempts this
167 /// subscription needs before it establishes.
168 retry_timer: RetryTimer,
169 /// The standing fault-question reservation (D-27/D-28), present iff
170 /// this subscription can ever need one.
171 fault_slot: Option<StandingSlot>,
172 /// A reservation for the permanent `Failed` completion a later retry
173 /// may discover (D-22), carved out when this subscription first became
174 /// `Pending` if the queue had room. Present or not, it rides through
175 /// every re-park this subscription goes through until it either
176 /// establishes (dropped, releasing the slot) or is spent on that
177 /// completion -- a terminal outcome must not be lost to best-effort
178 /// backpressure the way an ordinary batch can be.
179 terminal: Option<Reservation>,
180 /// Whether an interactive question is currently outstanding for this
181 /// subscription's open fault. While `true`, the retry timer is not
182 /// armed -- it waits for `Request::Answer` instead (D-27).
183 awaiting_answer: bool,
184 },
185 /// Routed into a coalesced directory watcher (D-6).
186 Routed {
187 directory: DirectoryId,
188 /// Kept because [`RetryMode`] is chosen at registration and consumed
189 /// later, by M5.3's fault protocol; the registration call is the only
190 /// place it can be stated (D-27).
191 options: WatchOptions,
192 },
193}
194
195impl Subscription {
196 fn options(&self) -> WatchOptions {
197 match self {
198 Subscription::Pending { options, .. } | Subscription::Routed { options, .. } => {
199 *options
200 }
201 }
202 }
203}
204
205/// The state only the servicing path may mutate.
206///
207/// Held behind a lock rather than owned outright by the drain because teardown
208/// reaches it too, from whichever thread dropped the monitor. The lock is
209/// uncontended in the steady state -- the drain is the only writer, by
210/// construction -- so it costs nothing and removes any question of what happens
211/// when teardown races a drain. `pub(crate)` (rather than private) only so a
212/// coalesced watcher's own background reopen can name `Weak<Mutex<Resident>>`
213/// as a field type and call [`rekey`] (M11.4); its fields stay private, so
214/// only this module ever mutates them.
215#[derive(Default)]
216pub(crate) struct Resident {
217 /// Every subscription, keyed by the identifier that tags its notifications.
218 subscriptions: HashMap<WatchId, Subscription>,
219 /// Every live coalesced watcher, keyed by directory identity (D-6): a
220 /// directory is watched once regardless of how many subscriptions target
221 /// entries within it.
222 directories: HashMap<DirectoryId, DirectoryWatcher>,
223}
224
225/// Re-key a coalesced watcher's entry after a path-based reopen fallback
226/// landed on a different `DirectoryId` than before (M11.4) -- previously
227/// fixed at first insertion and never updated, which would leave a later new
228/// subscription to the same path unable to find this watcher (it would look
229/// up the new id, find nothing, and spin up a redundant second watcher) and
230/// every existing subscription's own stored `directory` stale (breaking
231/// `Cancel`/`answer`'s own lookup by that id). A no-op if `old` is no longer
232/// present (the watcher was torn down and removed between the reopen and this
233/// call) or if `old == new` (a `ReOpenFile` success never reaches here at
234/// all, since it cannot change identity -- see `WatcherInner::retry_reestablish`).
235///
236/// `new` may already be occupied -- a path-based reopen can land on an
237/// identity another watcher already owns (for example, the reopened path was
238/// replaced by a junction into an already-watched directory, PR #20 review
239/// response). Silently `insert`-ing over that entry would drop the existing
240/// watcher (and every route it still serves) with nothing to migrate them:
241/// `Cancel`/`answer` would still find their subscriptions' `directory`
242/// pointing at `new`, but the map entry there is now a different watcher that
243/// never received their routes. So the existing entry's routes are migrated
244/// onto the just-rekeyed watcher instead, and the existing entry is discarded
245/// -- never the other way around: `watcher` is the caller's own `self`,
246/// executing this from inside its own retry-timer callback, and dropping it
247/// here (via `DirectoryWatcher::stop`) would deadlock waiting on that same
248/// callback to finish. A route that cannot be migrated -- reopening the
249/// directory races with it disappearing -- is not silently dropped either
250/// (PR #20 review response): its subscription is torn down with a terminal
251/// `Completion { Failed }`, the same way any other asynchronously discovered
252/// permanent open failure is reported, rather than left pointing at a route
253/// that no watcher holds.
254///
255/// The discarded existing entry is dropped only after the resident lock is
256/// released (PR #20 review response): its `Drop` calls `stop_and_drain` on
257/// its retry timer, which blocks waiting for that timer's own callback to
258/// finish -- and that callback, if it is concurrently blocked trying to
259/// re-enter `rekey` (or anything else that needs this same resident lock),
260/// would then wait on this thread forever while this thread waited on it.
261pub(crate) fn rekey(resident: &Mutex<Resident>, old: DirectoryId, new: DirectoryId) {
262 if old == new {
263 return;
264 }
265 let mut state = lock(resident);
266 let Some(watcher) = state.directories.remove(&old) else {
267 return;
268 };
269 let existing = state.directories.remove(&new);
270 if let Some(existing) = &existing {
271 for route in existing.take_routes() {
272 match DirectoryHandle::open(watcher.path()) {
273 Ok(handle) => watcher.add_route(route, handle),
274 Err(error) => {
275 // A route that cannot be migrated must not be silently
276 // dropped (PR #20 review response): its
277 // `Subscription::Routed` entry would otherwise keep
278 // reporting as registered while no watcher anywhere
279 // holds its route, so it can never receive another
280 // notification and a later `Cancel` would find nothing
281 // to remove. Reported the same way any other
282 // asynchronously discovered permanent open failure is
283 // (see `Opened::Failed`'s handling above): a terminal
284 // `Completion { Failed }`, best-effort since there is no
285 // reservation carved out for it here, and the stale
286 // subscription entry is removed so the client can
287 // resubscribe cleanly if it wants to keep watching.
288 log::warn!(
289 "windows-file-watcher: could not migrate a route from a redundant \
290 watcher during identity-collision coalescing: {error}"
291 );
292 let detail = error.detail();
293 let _ = route.sink.send(Notification::Completion {
294 watch: route.watch,
295 outcome: Outcome::Failed { detail },
296 });
297 state.subscriptions.remove(&route.watch);
298 }
299 }
300 }
301 }
302 state.directories.insert(new, watcher);
303 for subscription in state.subscriptions.values_mut() {
304 if let Subscription::Routed { directory, .. } = subscription
305 && *directory == old
306 {
307 *directory = new;
308 }
309 }
310 drop(state);
311 // Tears the redundant watcher down, if there was one: safe out here, but
312 // not under the resident lock above (see the doc comment).
313 drop(existing);
314}
315
316/// What a [`Session`] holds of its monitor.
317///
318/// Shared so a client can submit from its own threads, and so every session
319/// issues identifiers from one sequence -- a `WatchId` tags notifications and
320/// keys resident state, so two sessions must never mint the same one.
321///
322/// Deliberately does **not** contain the resident state: the handler captures
323/// that directly, and a handler reaching back through the object that owns its
324/// servicer would be a cycle.
325pub(crate) struct Core {
326 servicer: Servicer<Request>,
327 next_watch: AtomicU64,
328}
329
330impl Core {
331 /// Enqueue a request.
332 pub(crate) fn submit(&self, request: Request) -> Result<(), Rejected<Request>> {
333 self.servicer.submit(request)
334 }
335
336 /// Whether the monitor is still accepting requests.
337 pub(crate) fn is_open(&self) -> bool {
338 self.servicer.is_open()
339 }
340
341 /// Mint the next subscription identifier.
342 pub(crate) fn next_watch(&self) -> WatchId {
343 WatchId::from_raw(self.next_watch.fetch_add(1, Ordering::Relaxed))
344 }
345}
346
347/// Owns the servicing path and every watcher created through it.
348pub struct Monitor {
349 /// Shared with every [`Session`]. A session holding this alive past
350 /// `Monitor::Drop` keeps only the allocation: teardown closes the path, so a
351 /// surviving session reports itself shut and refuses requests rather than
352 /// reaching a monitor that is no longer there.
353 core: Arc<Core>,
354 resident: Arc<Mutex<Resident>>,
355}
356
357impl Monitor {
358 /// Create a monitor with an idle servicing path.
359 ///
360 /// # Errors
361 ///
362 /// Returns the error from creating the servicing path's work object.
363 pub fn new() -> io::Result<Self> {
364 let resident = Arc::new(Mutex::new(Resident::default()));
365
366 // A pending subscription's retry timer needs to reach `Core::submit`
367 // from its own callback, but `Core` cannot exist until after
368 // `Servicer::new` returns (the servicer is one of its fields) -- so this
369 // cell is captured by the handler now and filled in immediately below,
370 // strictly before any request can possibly be serviced.
371 let core_cell: Arc<OnceLock<Weak<Core>>> = Arc::new(OnceLock::new());
372
373 // The handler captures the resident state directly rather than reaching
374 // back through the monitor, which keeps "only the drain mutates resident
375 // state" visible in the types and avoids the cycle a handler holding its
376 // own servicer would create. `resident_weak` is handed to every newly
377 // constructed coalesced watcher (M11.4), so its own background reopen
378 // can re-key its `Resident.directories` entry without a strong cycle
379 // back to the map it lives in.
380 let state = Arc::clone(&resident);
381 let resident_weak = Arc::downgrade(&resident);
382 let core_ref = Arc::clone(&core_cell);
383 let servicer = Servicer::new(move |request: Request| {
384 service(&state, &resident_weak, &core_ref, request)
385 })?;
386
387 let core = Arc::new(Core {
388 servicer,
389 next_watch: AtomicU64::new(1),
390 });
391 core_cell
392 .set(Arc::downgrade(&core))
393 .unwrap_or_else(|_| unreachable!("the core cell is set exactly once, here"));
394
395 Ok(Self { core, resident })
396 }
397
398 /// Open a session, returning it with the receiver its notifications arrive on.
399 ///
400 /// Every watch created through the returned session delivers here (D-11), so
401 /// a client chooses its routing once rather than per subscription: one session
402 /// per consumer, and each consumer drains only what it asked for.
403 ///
404 /// The notification queue is bounded at [`DEFAULT_BOUND`]; use
405 /// [`Monitor::session_with_bound`] to choose.
406 #[must_use]
407 pub fn session(&self) -> (Session, Receiver) {
408 self.session_with_bound(DEFAULT_BOUND)
409 }
410
411 /// As [`Monitor::session`], with an explicit notification-queue bound.
412 ///
413 /// The bound counts notifications, not changes: one decoded completion is one
414 /// batch (D-10), which may carry hundreds of records.
415 #[must_use]
416 pub fn session_with_bound(&self, bound: NonZeroUsize) -> (Session, Receiver) {
417 let (sender, receiver) = channel_with_bound(bound);
418 (Session::new(Arc::clone(&self.core), sender), receiver)
419 }
420
421 /// Block until every request submitted so far has been serviced.
422 ///
423 /// Lets a caller observe resident state at a defined point rather than
424 /// polling it: registration is asynchronous by design (D-2), so without this
425 /// "no watcher was created" is indistinguishable from "not yet".
426 ///
427 /// Must not be called from inside the servicing path, which would be waiting
428 /// on itself.
429 pub fn quiesce(&self) {
430 self.core.servicer.quiesce();
431 }
432
433 /// How many subscriptions the monitor currently holds.
434 #[must_use]
435 pub fn watcher_count(&self) -> usize {
436 lock(&self.resident).subscriptions.len()
437 }
438
439 /// The retry mode a subscription registered with, if it is still live.
440 ///
441 /// The mode is stated at registration and consumed by M5.3's fault protocol;
442 /// this is what makes it observable in the meantime.
443 #[must_use]
444 pub fn retry_mode(&self, watch: WatchId) -> Option<RetryMode> {
445 lock(&self.resident)
446 .subscriptions
447 .get(&watch)
448 .map(|subscription| subscription.options().retry)
449 }
450
451 /// Whether a subscription is registered, established or not.
452 #[must_use]
453 pub fn is_registered(&self, watch: WatchId) -> bool {
454 lock(&self.resident).subscriptions.contains_key(&watch)
455 }
456
457 /// Whether a subscription currently has a live watcher.
458 ///
459 /// Distinct from [`Monitor::is_registered`]: a subscription whose target
460 /// cannot be opened yet is registered but not watching (D-14). Also false
461 /// once the routed watcher has stopped permanently (D-22) -- being
462 /// `Subscription::Routed` alone is not proof of liveness, since a stopped
463 /// watcher stays routed until its subscription is cancelled.
464 #[must_use]
465 pub fn is_watching(&self, watch: WatchId) -> bool {
466 let resident = lock(&self.resident);
467 let Some(Subscription::Routed { directory, .. }) = resident.subscriptions.get(&watch)
468 else {
469 return false;
470 };
471 resident
472 .directories
473 .get(directory)
474 .is_some_and(|watcher| watcher.stop_reason().is_none())
475 }
476
477 /// Why a subscription's watcher stopped *permanently*, if it has (D-22).
478 /// A watcher that is merely recovering ([`Monitor::is_faulted`]) reports
479 /// nothing here -- it is expected to resolve on its own (D-14).
480 #[must_use]
481 pub fn stop_reason(&self, watch: WatchId) -> Option<io::Error> {
482 let resident = lock(&self.resident);
483 let Some(Subscription::Routed { directory, .. }) = resident.subscriptions.get(&watch)
484 else {
485 return None;
486 };
487 resident
488 .directories
489 .get(directory)
490 .and_then(DirectoryWatcher::stop_reason)
491 }
492
493 /// Whether a subscription's watcher is currently working to re-establish
494 /// itself (D-31): asking, awaiting an answer, or backed off. `None` if the
495 /// subscription is not registered. A still-`Pending` subscription always
496 /// counts, whether this is its first attempt or a later one after an
497 /// outage -- either way it is not currently delivering and the monitor is
498 /// working to change that (D-14 is why neither case is ever terminal).
499 #[must_use]
500 pub fn is_faulted(&self, watch: WatchId) -> Option<bool> {
501 let resident = lock(&self.resident);
502 match resident.subscriptions.get(&watch)? {
503 // Being Pending at all means at least one open attempt already
504 // failed retryably (D-22) -- whether it is currently awaiting an
505 // interactive answer or backed off on its timer, it is recovering.
506 Subscription::Pending { .. } => Some(true),
507 Subscription::Routed { directory, .. } => resident
508 .directories
509 .get(directory)
510 .map(DirectoryWatcher::is_faulted),
511 }
512 }
513
514 /// The classification and raw code behind a subscription's current fault,
515 /// if any (D-79) -- the same detail an interactive route was, or would
516 /// have been, asked about. `None` if the subscription is not registered,
517 /// still `Pending` (D-22's initial open retry loop tracks no persistent
518 /// detail of its own), or not currently faulted.
519 #[must_use]
520 pub fn fault_detail(&self, watch: WatchId) -> Option<FaultDetail> {
521 let resident = lock(&self.resident);
522 let Some(Subscription::Routed { directory, .. }) = resident.subscriptions.get(&watch)
523 else {
524 return None;
525 };
526 resident
527 .directories
528 .get(directory)
529 .and_then(DirectoryWatcher::fault_detail)
530 }
531
532 /// Whether the monitor is still accepting requests.
533 #[must_use]
534 pub fn is_running(&self) -> bool {
535 self.core.is_open()
536 }
537
538 /// Stop servicing and tear down every watcher, blocking until it is done.
539 ///
540 /// Idempotent, so a caller may shut down explicitly and still let `Drop` run.
541 /// After it returns, no handler and no completion callback is executing or can
542 /// start, and every outstanding read has been cancelled (D-20).
543 pub fn shut_down(&self) {
544 // Order matters: closing the servicing path first means nothing can adopt
545 // a watcher after the table below has been walked. The other order leaves
546 // an armed read owned by nobody (D-23/D-34).
547 self.core.servicer.shut_down();
548
549 // Each watcher's drop cancels its outstanding read and waits for its
550 // callbacks, so this is where the blocking teardown of D-20 actually
551 // happens. Taken out of the table first, so the lock is not held across
552 // the waits -- a completion callback that is still finishing has no reason
553 // to be blocked on it, and holding it would invite exactly the
554 // wait-on-yourself deadlock `stop` documents.
555 let mut resident = lock(&self.resident);
556 let directories = std::mem::take(&mut resident.directories);
557 resident.subscriptions.clear();
558 drop(resident);
559 drop(directories);
560 }
561
562 /// How many distinct coalesced watchers are live, as opposed to how many
563 /// subscriptions there are (D-6). Test-only: a client has no reason to
564 /// distinguish the two, since coalescing is an implementation detail.
565 #[cfg(test)]
566 pub(crate) fn directory_count(&self) -> usize {
567 lock(&self.resident).directories.len()
568 }
569}
570
571/// Apply one request to the resident state.
572///
573/// Runs on the servicing path, one call at a time, so nothing here needs to
574/// consider a concurrent mutation (D-2).
575fn service(
576 resident: &Mutex<Resident>,
577 resident_weak: &Weak<Mutex<Resident>>,
578 core_ref: &Arc<OnceLock<Weak<Core>>>,
579 request: Request,
580) {
581 match request {
582 Request::Subscribe {
583 watch,
584 path,
585 options,
586 sink,
587 completion,
588 fault_slot,
589 } => {
590 let outcome = subscribe(
591 resident,
592 resident_weak,
593 core_ref,
594 watch,
595 path,
596 options,
597 sink,
598 fault_slot,
599 );
600 completion.send(Notification::Completion { watch, outcome });
601 }
602 Request::Cancel { watch, completion } => {
603 // Removed under the lock, dropped outside it: dropping tears the
604 // watcher down, which blocks on its callbacks, and holding the
605 // resident lock across that wait would serialise teardown against
606 // every other reader for no reason.
607 let torn_down = {
608 let mut state = lock(resident);
609 let mut torn_down = None;
610 if let Some(Subscription::Routed { directory, .. }) =
611 state.subscriptions.remove(&watch)
612 && let Some((remaining, stopped)) = state
613 .directories
614 .get(&directory)
615 .map(|watcher| watcher.remove_route(watch))
616 {
617 // A volume-change resolution this removal triggered may
618 // have decided `Stop` for other routes on the same
619 // watcher too (PR #20 review response); their
620 // subscriptions are now just as stale as this one's,
621 // already removed above.
622 for extra in stopped {
623 state.subscriptions.remove(&extra);
624 }
625 if remaining == 0 {
626 torn_down = state.directories.remove(&directory);
627 }
628 }
629 torn_down
630 };
631 drop(torn_down);
632
633 // Sent only once the watcher is fully stopped, which is what makes
634 // the ordering guarantee structural: nothing from this subscription
635 // can be enqueued after this point, so a client seeing `Cancelled`
636 // knows everything before it belongs to the live watch and nothing
637 // after it does (D-30).
638 completion.send(Notification::Completion {
639 watch,
640 outcome: Outcome::Cancelled,
641 });
642 }
643 Request::Retry { watch } => retry_pending(resident, resident_weak, core_ref, watch),
644 Request::Answer { watch, delay } => answer(resident, watch, delay),
645 Request::AnswerVolumeChange { watch, decision } => {
646 answer_volume_change(resident, watch, decision);
647 }
648 }
649}
650
651/// Resolve a client's answer to an interactive fault question (D-27/M5.3),
652/// wherever it currently lives -- a still-`Pending` subscription's own open
653/// fault, or a routed subscription's coalesced watcher. A no-op if `watch` is
654/// not currently awaiting one (already resolved, already cancelled, or never
655/// asked).
656fn answer(resident: &Mutex<Resident>, watch: WatchId, delay: Option<Duration>) {
657 let mut state = lock(resident);
658 if let Some(Subscription::Pending {
659 awaiting_answer, ..
660 }) = state.subscriptions.get(&watch)
661 && *awaiting_answer
662 {
663 let resolved = delay.unwrap_or_else(|| FaultOperation::Open.default_delay());
664 if let Some(Subscription::Pending {
665 retry_timer,
666 awaiting_answer,
667 ..
668 }) = state.subscriptions.get_mut(&watch)
669 {
670 *awaiting_answer = false;
671 retry_timer.set_after(clamp(resolved));
672 }
673 return;
674 }
675 if let Some(Subscription::Routed { directory, .. }) = state.subscriptions.get(&watch)
676 && let Some(watcher) = state.directories.get(directory)
677 {
678 watcher.answer(watch, delay);
679 }
680}
681
682/// Resolve a client's answer to a volume-change question (D-78/M12),
683/// wherever it currently lives -- always a routed subscription's coalesced
684/// watcher, since a volume-change question is only ever raised by a
685/// path-based reopen of an already-established watcher. A no-op if `watch`
686/// is not currently awaiting one (already resolved, already cancelled, or
687/// never asked).
688fn answer_volume_change(
689 resident: &Mutex<Resident>,
690 watch: WatchId,
691 decision: VolumeChangeDecision,
692) {
693 // Removed under the lock, dropped outside it, mirroring `Request::Cancel`:
694 // dropping tears the watcher down, which blocks on its callbacks.
695 let torn_down = {
696 let mut state = lock(resident);
697 let Some(Subscription::Routed { directory, .. }) = state.subscriptions.get(&watch) else {
698 return;
699 };
700 let directory = *directory;
701 let Some((remaining, stopped)) = state
702 .directories
703 .get(&directory)
704 .and_then(|watcher| watcher.answer_volume_change(watch, decision))
705 else {
706 return;
707 };
708 // Every watch that decided `Stop` -- including `watch` itself, if
709 // that was its own decision -- no longer has a route on this
710 // watcher, so its `Resident.subscriptions` entry is stale and would
711 // otherwise keep reporting as registered/routed forever (PR #20
712 // review response).
713 for stopped_watch in &stopped {
714 state.subscriptions.remove(stopped_watch);
715 }
716 if remaining == 0 {
717 state.directories.remove(&directory)
718 } else {
719 None
720 }
721 };
722 drop(torn_down);
723}
724
725/// What opening a subscription's target found, and how it should route within
726/// whatever was opened (D-7).
727enum Opened {
728 /// A live handle, plus how this subscription should route within it and the
729 /// exact path that was opened (M5.1 needs this to reopen on re-establish;
730 /// it is `path` for a directory target, `path`'s parent for a file one).
731 Handle {
732 handle: DirectoryHandle,
733 scope: RouteScope,
734 opened_path: PathBuf,
735 },
736 /// Retryable (D-22): nothing to watch yet.
737 Pending(FaultDetail),
738 /// Permanent (D-22): nothing can ever be watched here.
739 Failed(FaultDetail),
740}
741
742/// Try to open a subscription's target, resolving a file target to its parent
743/// (D-7).
744///
745/// A subscription names a *path*; whether that path is a directory or a file is
746/// not known in advance, only once the open is attempted. `NotADirectory` --
747/// something exists at `path`, but it is not a directory -- is exactly the
748/// signal that flips this from a directory subscription to a file one, since it
749/// is D-22's classification for precisely that condition.
750fn open_target(path: &std::path::Path, subtree: bool) -> Opened {
751 match DirectoryHandle::open(path) {
752 Ok(handle) => Opened::Handle {
753 handle,
754 scope: RouteScope::Directory { subtree },
755 opened_path: path.to_path_buf(),
756 },
757 Err(error) if error.failure() == OpenFailure::NotADirectory => open_file_target(path),
758 Err(error) if error.failure().is_retryable() => Opened::Pending(error.detail()),
759 Err(error) => Opened::Failed(error.detail()),
760 }
761}
762
763/// Open a file target's parent directory, filtered to the file's own leaf name.
764///
765/// Never recursive: a file is always a direct child of the directory that is
766/// actually opened (D-7).
767fn open_file_target(path: &std::path::Path) -> Opened {
768 let (Some(parent), Some(leaf)) = (path.parent(), path.file_name()) else {
769 // A path with no parent (a bare volume root) or no final component
770 // cannot be a file target; report the failure that led here.
771 return Opened::Failed(FaultDetail::synthetic(
772 OpenFailure::NotADirectory,
773 ERROR_DIRECTORY,
774 ));
775 };
776 // A bare relative leaf (`target.txt`) has an empty `parent()`, which
777 // `CreateFileW` rejects outright -- normalize it to `.` (the current
778 // directory) so this target actually opens instead of spuriously
779 // reporting a permanent or retryable failure that has nothing to do with
780 // the target itself.
781 let parent = if parent.as_os_str().is_empty() {
782 std::path::Path::new(".")
783 } else {
784 parent
785 };
786 match DirectoryHandle::open(parent) {
787 Ok(handle) => Opened::Handle {
788 handle,
789 scope: RouteScope::File {
790 leaf: Wtf16String::from_os_str(leaf),
791 },
792 opened_path: parent.to_path_buf(),
793 },
794 Err(error) if error.failure().is_retryable() => Opened::Pending(error.detail()),
795 Err(error) => Opened::Failed(error.detail()),
796 }
797}
798
799/// Whether an open-class fault must wait for this route's interactive answer.
800fn awaits_open_answer(retry: RetryMode, has_fault_slot: bool) -> bool {
801 retry == RetryMode::Interactive && has_fault_slot
802}
803
804/// Build the timer that fires this subscription's next open retry (M5.1). The
805/// callback submits `Request::Retry` through a `Weak<Core>`, resolved lazily
806/// (see `Monitor::new`) because `Core` cannot exist until after the servicing
807/// path that this timer's owner is registered on does.
808fn make_retry_timer(
809 core_ref: &Arc<OnceLock<Weak<Core>>>,
810 watch: WatchId,
811) -> io::Result<RetryTimer> {
812 let core_ref = Arc::clone(core_ref);
813 ThreadpoolTimer::new(
814 move |_firing| {
815 if let Some(core) = core_ref.get().and_then(Weak::upgrade) {
816 let _ = core.submit(Request::Retry { watch });
817 }
818 },
819 None,
820 )
821 .map(RetryTimer)
822}
823
824/// A retry timer that drains itself when it goes.
825///
826/// A newtype rather than a bare [`ThreadpoolTimer`] because a subscription's
827/// timer is dropped at several scattered points -- when it establishes, when it
828/// fails permanently, and when the monitor shuts down -- and an armed timer owes
829/// a drain at every one of them. Field drop would make that drain anyway, so
830/// this adds no blocking; what it adds is that the obligation cannot be left
831/// undischarged at a site somebody forgot, which `windows-threadpool-sys`
832/// reports and, under its `fail-fast` feature, panics on.
833struct RetryTimer(ThreadpoolTimer);
834
835impl RetryTimer {
836 fn set_after(&self, delay: Duration) {
837 self.0.set_after(delay);
838 }
839}
840
841impl Drop for RetryTimer {
842 fn drop(&mut self) {
843 self.0.stop_and_drain();
844 }
845}
846
847/// Park a subscription as `Pending` after a retryable open failure (D-22),
848/// asking its interactive question (D-27) or arming the default-delay retry.
849/// Used both for a subscription's very first attempt and for every later one
850/// that is still retryable. `detail` is the classified failure that made this
851/// attempt retryable (D-79), carried through to the interactive question.
852#[allow(clippy::too_many_arguments)]
853fn park_pending(
854 resident: &Mutex<Resident>,
855 core_ref: &Arc<OnceLock<Weak<Core>>>,
856 watch: WatchId,
857 path: PathBuf,
858 options: WatchOptions,
859 sink: Sender,
860 fault_slot: Option<StandingSlot>,
861 detail: FaultDetail,
862) -> io::Result<()> {
863 let retry_timer = make_retry_timer(core_ref, watch)?;
864 // Best-effort: if the queue has no room to spare right now, this
865 // subscription's eventual permanent failure (rare) falls back to the
866 // ordinary best-effort path rather than blocking registration on it.
867 let terminal = sink.reserve();
868 let awaiting_answer = awaits_open_answer(options.retry, fault_slot.is_some());
869 let mut state = lock(resident);
870 state.subscriptions.insert(
871 watch,
872 Subscription::Pending {
873 path,
874 options,
875 sink,
876 retry_timer,
877 fault_slot,
878 terminal,
879 awaiting_answer,
880 },
881 );
882 // Arm or ask from the entry just inserted, under the same lock: no window
883 // in which the timer could fire before the subscription it retries exists.
884 if let Some(Subscription::Pending {
885 retry_timer,
886 fault_slot,
887 ..
888 }) = state.subscriptions.get(&watch)
889 {
890 if awaiting_answer {
891 if let Some(slot) = fault_slot {
892 slot.send(Notification::RetryQuestion {
893 watch,
894 operation: FaultOperation::Open,
895 detail,
896 });
897 }
898 } else {
899 retry_timer.set_after(clamp(FaultOperation::Open.default_delay()));
900 }
901 }
902 Ok(())
903}
904
905/// Whether a settled-tier notification accurately describes this route now.
906fn should_report_established(report_liveness: bool, is_faulted: bool) -> bool {
907 report_liveness && !is_faulted
908}
909
910/// Route a successfully opened target into a coalesced watcher (D-6), starting
911/// one if this is the first subscription to reach this directory.
912///
913/// `Established` (D-13, opt-in) is sent whenever this succeeds, reporting
914/// whichever tier the directory actually settled on (D-17) -- on the very
915/// first establishment as well as a later one, matching its own documented
916/// contract ("reported once at first establishment and again after every
917/// re-establishment").
918///
919/// `original_path` and `core_ref` are needed only for the fallback: if the
920/// watcher itself fails to arm despite a successful open (rare -- D-15's
921/// rearm-and-retry case), this parks the subscription as `Pending` again
922/// rather than losing it, and a fresh open retry needs the client's original
923/// path (which may re-resolve differently, D-7) and a working retry timer.
924#[allow(clippy::too_many_arguments)]
925/// Routes a freshly opened handle to its watcher, coalescing with an existing
926/// one for the same directory (D-6) or starting a new [`DirectoryWatcher`].
927fn route_established(
928 resident: &Mutex<Resident>,
929 resident_weak: &Weak<Mutex<Resident>>,
930 core_ref: &Arc<OnceLock<Weak<Core>>>,
931 watch: WatchId,
932 original_path: PathBuf,
933 handle: DirectoryHandle,
934 scope: RouteScope,
935 opened_path: PathBuf,
936 options: WatchOptions,
937 sink: Sender,
938 fault_slot: Option<StandingSlot>,
939) -> Routed {
940 let id = handle.identity();
941 let route = Route {
942 watch,
943 scope,
944 sink: sink.clone(),
945 retry: options.retry,
946 report_liveness: options.report_liveness,
947 on_volume_change: options.on_volume_change,
948 fault_slot,
949 };
950 let mut state = lock(resident);
951 if let Some(watcher) = state
952 .directories
953 .get(&id)
954 .filter(|watcher| watcher.stop_reason().is_none())
955 {
956 // Coalesce (D-6): this directory already has a watcher. `handle` is
957 // handed to it too, in case this route needs to widen the reach to
958 // recursive (M4.4) -- reopening is what that takes, and this handle is
959 // exactly what a reopen needs, so nothing further is opened for it.
960 watcher.add_route(route, handle);
961 let mode = watcher.mode();
962 // Read before `state.subscriptions.insert` below, which needs `state`
963 // mutably while `watcher` still borrows it immutably.
964 let is_faulted = watcher.is_faulted();
965 state.subscriptions.insert(
966 watch,
967 Subscription::Routed {
968 directory: id,
969 options,
970 },
971 );
972 drop(state);
973 // Suppressed while the watcher is faulted (PR #20 review response):
974 // either it was already recovering before this route joined, or
975 // `add_route`'s own widen-to-recursive reopen just failed and entered
976 // the fault loop -- either way there is no settled tier to report
977 // right now, and asserting one would contradict `Established`'s
978 // documented contract ("whichever tier the directory actually
979 // settled on"). This route is still added to `routes` either way, so
980 // it already received (or is about to receive) the ordinary
981 // `Suspended`/`RetryQuestion` fault notifications, and will get its
982 // own `Resumed`/`Established` from `resolve_fault_success` once (if)
983 // the watcher recovers.
984 if should_report_established(options.report_liveness, is_faulted) {
985 let _ = sink.send(Notification::Established { watch, mode });
986 }
987 return Routed::Live;
988 }
989
990 // Either nothing is watching this directory yet, or what remains there
991 // stopped permanently (D-22) and can never arm again -- discard it before
992 // starting fresh from this route's own handle, rather than silently
993 // reporting a live subscription against a watcher that will never
994 // deliver. Removed under the lock, dropped outside it: `Drop` blocks on
995 // rundown (D-20), and holding the resident lock across that wait would
996 // serialise every other reader against a stopped watcher for no reason
997 // (the same ordering `Request::Cancel` already uses).
998 let stale = state.directories.remove(&id);
999 drop(state);
1000 drop(stale);
1001
1002 match DirectoryWatcher::start(handle, opened_path, route) {
1003 Ok(watcher) => {
1004 // M11.4: so this watcher's own background reopen can re-key its
1005 // `Resident.directories` entry if a path-based fallback ever
1006 // lands on a different directory.
1007 watcher.bind_resident(Weak::clone(resident_weak));
1008 let mode = watcher.mode();
1009 let mut state = lock(resident);
1010 state.directories.insert(id, watcher);
1011 state.subscriptions.insert(
1012 watch,
1013 Subscription::Routed {
1014 directory: id,
1015 options,
1016 },
1017 );
1018 drop(state);
1019 if options.report_liveness {
1020 let _ = sink.send(Notification::Established { watch, mode });
1021 }
1022 Routed::Live
1023 }
1024 Err((error, route)) => {
1025 // Arming failed against a directory that just opened -- D-15's
1026 // rearm-and-retry classification, not fatal. `start` hands the
1027 // route back on failure, so its standing fault-question
1028 // reservation (if any) is reused here rather than silently
1029 // downgrading an `Interactive` subscription to default retries.
1030 let detail = classify_detail(&error);
1031 match park_pending(
1032 resident,
1033 core_ref,
1034 watch,
1035 original_path,
1036 options,
1037 sink,
1038 route.fault_slot,
1039 detail,
1040 ) {
1041 Ok(()) => Routed::Parked,
1042 Err(error) => Routed::ParkFailed(FaultDetail::retry_unavailable(&error)),
1043 }
1044 }
1045 }
1046}
1047
1048/// What became of routing a freshly opened handle into a watcher (see
1049/// [`route_established`]).
1050enum Routed {
1051 /// Coalesced onto an existing watcher, or a new one started and armed: a
1052 /// live watcher now backs this subscription.
1053 Live,
1054 /// Starting a *new* watcher failed immediately after its directory opened
1055 /// (D-15's rearm-and-retry case); the subscription was re-parked instead.
1056 Parked,
1057 /// Even the fallback park could not be set up (its retry timer failed to
1058 /// be created -- vanishingly rare resource exhaustion); nothing was
1059 /// registered for this subscription.
1060 ParkFailed(FaultDetail),
1061}
1062
1063/// Re-attempt establishing a still-`Pending` subscription (M5.1), after its
1064/// retry timer fired. A no-op if the subscription is no longer `Pending`
1065/// (already routed by some other path, or already cancelled).
1066fn retry_pending(
1067 resident: &Mutex<Resident>,
1068 resident_weak: &Weak<Mutex<Resident>>,
1069 core_ref: &Arc<OnceLock<Weak<Core>>>,
1070 watch: WatchId,
1071) {
1072 let taken = {
1073 let mut state = lock(resident);
1074 match state.subscriptions.remove(&watch) {
1075 Some(Subscription::Pending {
1076 path,
1077 options,
1078 sink,
1079 retry_timer,
1080 fault_slot,
1081 terminal,
1082 ..
1083 }) => Some((path, options, sink, retry_timer, fault_slot, terminal)),
1084 Some(other) => {
1085 state.subscriptions.insert(watch, other);
1086 None
1087 }
1088 None => None,
1089 }
1090 };
1091 let Some((path, options, sink, retry_timer, fault_slot, terminal)) = taken else {
1092 return;
1093 };
1094
1095 match open_target(&path, options.subtree) {
1096 Opened::Pending(detail) => {
1097 let awaiting_answer = awaits_open_answer(options.retry, fault_slot.is_some());
1098 let mut state = lock(resident);
1099 state.subscriptions.insert(
1100 watch,
1101 Subscription::Pending {
1102 path,
1103 options,
1104 sink,
1105 retry_timer,
1106 fault_slot,
1107 terminal,
1108 awaiting_answer,
1109 },
1110 );
1111 if let Some(Subscription::Pending {
1112 retry_timer,
1113 fault_slot,
1114 ..
1115 }) = state.subscriptions.get(&watch)
1116 {
1117 if awaiting_answer {
1118 if let Some(slot) = fault_slot {
1119 slot.send(Notification::RetryQuestion {
1120 watch,
1121 operation: FaultOperation::Open,
1122 detail,
1123 });
1124 }
1125 } else {
1126 retry_timer.set_after(clamp(FaultOperation::Open.default_delay()));
1127 }
1128 }
1129 }
1130 Opened::Failed(detail) => {
1131 // Permanent, discovered only on a later retry rather than at
1132 // registration: genuinely rare (the target existed retryably, then
1133 // became permanently unwatchable), but still a terminal outcome the
1134 // client must not silently lose to backpressure -- delivered
1135 // through `terminal`'s reservation when park_pending managed to
1136 // carve one out, falling back to best-effort only if it could not.
1137 // `retry_timer` and `fault_slot` are dropped here along with the
1138 // subscription, which is already removed from `resident`.
1139 let outcome = Outcome::Failed { detail };
1140 match terminal {
1141 Some(reservation) => reservation.send(Notification::Completion { watch, outcome }),
1142 None => {
1143 let _ = sink.send(Notification::Completion { watch, outcome });
1144 }
1145 }
1146 }
1147 Opened::Handle {
1148 handle,
1149 scope,
1150 opened_path,
1151 } => {
1152 // Background retry path: no synchronous caller is waiting on an
1153 // `Outcome` here, but a `ParkFailed` fallback is still a terminal
1154 // outcome the client was never told about otherwise, so report it
1155 // (best-effort -- `terminal` was already consumed or never taken
1156 // for this attempt).
1157 let outcome_sink = sink.clone();
1158 match route_established(
1159 resident,
1160 resident_weak,
1161 core_ref,
1162 watch,
1163 path,
1164 handle,
1165 scope,
1166 opened_path,
1167 options,
1168 sink,
1169 fault_slot,
1170 ) {
1171 Routed::Live | Routed::Parked => {}
1172 Routed::ParkFailed(detail) => {
1173 let _ = outcome_sink.send(Notification::Completion {
1174 watch,
1175 outcome: Outcome::Failed { detail },
1176 });
1177 }
1178 }
1179 }
1180 }
1181}
1182
1183/// Register one subscription, reporting what became of it.
1184#[allow(clippy::too_many_arguments)]
1185fn subscribe(
1186 resident: &Mutex<Resident>,
1187 resident_weak: &Weak<Mutex<Resident>>,
1188 core_ref: &Arc<OnceLock<Weak<Core>>>,
1189 watch: WatchId,
1190 path: PathBuf,
1191 options: WatchOptions,
1192 sink: Sender,
1193 fault_slot: Option<StandingSlot>,
1194) -> Outcome {
1195 match open_target(&path, options.subtree) {
1196 Opened::Pending(detail) => {
1197 match park_pending(
1198 resident, core_ref, watch, path, options, sink, fault_slot, detail,
1199 ) {
1200 Ok(()) => Outcome::Establishing,
1201 Err(error) => Outcome::Failed {
1202 detail: FaultDetail::retry_unavailable(&error),
1203 },
1204 }
1205 }
1206 Opened::Failed(detail) => Outcome::Failed { detail },
1207 Opened::Handle {
1208 handle,
1209 scope,
1210 opened_path,
1211 } => {
1212 // A failed start immediately after opening falls back to
1213 // `Pending` (D-15's rearm-and-retry case) rather than routing to
1214 // a live watcher, so the client must be told it is still
1215 // establishing, not that it is already subscribed; a `ParkFailed`
1216 // fallback means neither happened, so the client is told this
1217 // registration simply failed.
1218 match route_established(
1219 resident,
1220 resident_weak,
1221 core_ref,
1222 watch,
1223 path,
1224 handle,
1225 scope,
1226 opened_path,
1227 options,
1228 sink,
1229 fault_slot,
1230 ) {
1231 Routed::Live => Outcome::Subscribed,
1232 Routed::Parked => Outcome::Establishing,
1233 Routed::ParkFailed(detail) => Outcome::Failed { detail },
1234 }
1235 }
1236 }
1237}
1238
1239impl Drop for Monitor {
1240 fn drop(&mut self) {
1241 self.shut_down();
1242 }
1243}
1244
1245impl std::fmt::Debug for Monitor {
1246 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1247 f.debug_struct("Monitor")
1248 .field("running", &self.is_running())
1249 .field("watchers", &self.watcher_count())
1250 .finish_non_exhaustive()
1251 }
1252}
1253
1254/// Lock, recovering the guard if a previous holder panicked.
1255fn lock<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
1256 mutex.lock().unwrap_or_else(|poison| poison.into_inner())
1257}
1258
1259#[cfg(test)]
1260mod tests;