Skip to main content

windows_file_watcher/
retry.rs

1// Copyright (c) 2026 Mike Grier
2//! The retry protocol (D-27): fixed per-operation defaults, a floor, and the
3//! earliest-answer reduction over a fault's asked subscriptions.
4//!
5//! `WatchOptions` carries only [`crate::watch::RetryMode`]'s two variants --
6//! `Defaults` or `Interactive` -- with no numeric override. So unlike the
7//! aspirational "soonest-recovering reduction" language in the crate's fault
8//! model notes (growth multiplier, cap, jitter, per-error-kind override), there
9//! is no field anywhere a caller could use to state one of those, and this
10//! module does not invent behaviour nobody can configure. What is implemented is
11//! exactly D-27's literal text: a fixed delay per failing operation, asked of
12//! every interactive subscription, resolved to the earliest answer (a decliner
13//! counted at the default), and clamped to a floor.
14
15use std::time::Duration;
16
17/// The delay used when nothing overrides it, and nobody was asked. Also every
18/// interactive decliner's answer.
19///
20/// One value for both operations, per `Azure/m`'s shipped code (D-27); kept as
21/// two constants because D-15 nonetheless keeps the operations texturally
22/// distinct and a future divergence should not have to touch every call site.
23pub(crate) const OPEN_DEFAULT_DELAY: Duration = Duration::from_millis(500);
24pub(crate) const ARM_DEFAULT_DELAY: Duration = Duration::from_millis(500);
25
26/// No answer, from anyone, is ever honoured below this. Protects against a hot
27/// retry loop driven by a misbehaving or miscoded interactive answer.
28pub(crate) const FLOOR: Duration = Duration::from_millis(50);
29
30/// Which failing operation a fault arose from, matching D-15's reopen-retry /
31/// rearm-retry split. Each has its own default delay.
32#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
33pub enum FaultOperation {
34    /// The directory (or a file target's parent) could not be opened.
35    Open,
36    /// A `ReadDirectoryChangesW` completion reported a failure, or resubmitting
37    /// one did.
38    Arm,
39}
40
41impl FaultOperation {
42    /// The delay used when nobody interactive is asked, or everyone declines.
43    #[must_use]
44    pub(crate) fn default_delay(self) -> Duration {
45        match self {
46            FaultOperation::Open => OPEN_DEFAULT_DELAY,
47            FaultOperation::Arm => ARM_DEFAULT_DELAY,
48        }
49    }
50}
51
52/// The mode a watch is established in (D-13/D-17).
53#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
54#[non_exhaustive]
55pub enum WatchMode {
56    /// `ReadDirectoryChangesW` on a `ThreadpoolIo`.
57    Detailed,
58    /// `FindFirstChangeNotification` on a `ThreadpoolWait` (M6): the universal
59    /// floor, reached when the volume does not support the detailed API.
60    Coarse,
61}
62
63/// Clamp a resolved delay to the floor.
64#[must_use]
65pub(crate) fn clamp(delay: Duration) -> Duration {
66    delay.max(FLOOR)
67}
68
69#[cfg(test)]
70mod tests;