Skip to main content

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;