oxedyne/fe2o3/fe2o3_file/src/quiet.rs
5.0 KiB, 5 runs
created by r1870400018:63095, which is this file's identity for as long as the history lasts, whatever it is later renamed to
download · who wrote it · its history
| 1 | //! A pure stillness detector: has a changing reading gone quiet? |
| 2 | //! |
| 3 | //! [`Quiet`] holds no clock and does no I/O of its own. The caller takes its own reading of |
| 4 | //! whatever it is watching -- a directory survey's fingerprint, a poll loop's snapshot, anything |
| 5 | //! comparable by equality -- and hands it to [`Quiet::poll`] along with the time of the poll. |
| 6 | //! `Quiet` answers with a [`Stillness`]: still moving, settling, still, or restarted. |
| 7 | //! |
| 8 | //! # The gap guard |
| 9 | //! |
| 10 | //! A poll loop is not always running. A process that is stopped (SIGSTOP, a debugger) or swapped |
| 11 | //! out between one poll and the next watched nothing during the gap, and waking is not the |
| 12 | //! stillness of an unchanged reading. So a gap between two polls of more than `gap_factor` times |
| 13 | //! the caller's expected poll interval restarts the quiet window, reporting |
| 14 | //! [`Stillness::Restarted`] rather than [`Stillness::Still`] at once. The interval is supplied on |
| 15 | //! each call rather than fixed at construction, since a caller may lengthen its own poll interval |
| 16 | //! over a run, to keep a large tree's survey under a fixed share of one core. |
| 17 | //! |
| 18 | //! The guard does not see the machine suspend, on Linux. [`Instant`] reads `CLOCK_MONOTONIC`, |
| 19 | //! which stops while the machine sleeps, so a suspended hour is neither a gap nor an hour of |
| 20 | //! stillness: the time is not counted at all, and a reading that held across it goes on with its |
| 21 | //! window where it left off. A caller that must take a fresh reading on resume has to notice the |
| 22 | //! resume itself, by comparing `CLOCK_BOOTTIME`, which counts suspend, against `Instant` (the |
| 23 | //! `Asleep` check in `fe2o3_sys::clock` does), and then call [`Quiet::restart`]. |
| 24 | //! |
| 25 | //! [Written with AI](https://need2know.ai/with-ai/code)\ |
| 26 | //! Anthropic Claude |
| 27 | |
| 28 | use std::time::{ |
| 29 | Duration, |
| 30 | Instant, |
| 31 | }; |
| 32 | |
| 33 | |
| 34 | /// What one poll found, relative to the reading and the time of the poll before it. |
| 35 | #[derive(Clone, Copy, Debug, PartialEq, Eq)] |
| 36 | pub enum Stillness { |
| 37 | Moved, // the reading differs from the one at the previous poll |
| 38 | Settling(Duration), // unchanged, but short of the quiet window; time still owed |
| 39 | Still, // unchanged for at least the quiet window |
| 40 | Restarted, // the gap since the last poll exceeded the guard; the window restarts here |
| 41 | } |
| 42 | |
| 43 | /// The stillness state machine. |
| 44 | /// |
| 45 | /// Construct with [`Quiet::new`] and feed it with [`Quiet::poll`]. `T` is whatever the caller |
| 46 | /// compares readings as -- a hash, a fingerprint struct, a `BTreeMap` snapshot -- `Quiet` never |
| 47 | /// looks inside it, only at whether it equals the last one seen. |
| 48 | #[derive(Clone, Debug)] |
| 49 | pub struct Quiet<T> { |
| 50 | quiet: Duration, // how long a reading must hold before it counts as still |
| 51 | gap_factor: u32, // a poll gap beyond this multiple of the poll interval restarts the window |
| 52 | reading: Option<T>, // the reading last seen |
| 53 | changed_at: Option<Instant>, // when `reading` last changed |
| 54 | last_poll: Option<Instant>, // when `poll` was last called, for the gap guard |
| 55 | } |
| 56 | |
| 57 | impl<T: PartialEq> Quiet<T> { |
| 58 | |
| 59 | /// A quiet window of `quiet`, with the default gap guard of 3 poll intervals. |
| 60 | pub fn new(quiet: Duration) -> Self { |
| 61 | Self::with_gap_factor(quiet, 3) |
| 62 | } |
| 63 | |
| 64 | /// As [`Quiet::new`], with the gap guard's multiple of the poll interval given explicitly. |
| 65 | pub fn with_gap_factor(quiet: Duration, gap_factor: u32) -> Self { |
| 66 | Self { |
| 67 | quiet, |
| 68 | gap_factor, |
| 69 | reading: None, |
| 70 | changed_at: None, |
| 71 | last_poll: None, |
| 72 | } |
| 73 | } |
| 74 | |
| 75 | /// Feeds one poll's reading, taken at `now`, with polls expected roughly `poll_interval` apart. |
| 76 | /// |
| 77 | /// `last_poll` is stamped here on every call, whichever arm is taken below -- a run of ordinary |
| 78 | /// polls must never by itself trip the gap guard, which is the bug `ore-quiet-mark`'s bash |
| 79 | /// loop had: it stamped the "last seen" time on only some of its paths, so its own regular |
| 80 | /// polling could restart its window. |
| 81 | pub fn poll(&mut self, reading: T, now: Instant, poll_interval: Duration) -> Stillness { |
| 82 | let gap = self.last_poll.map(|last| now.saturating_duration_since(last)); |
| 83 | self.last_poll = Some(now); |
| 84 | if let Some(gap) = gap { |
| 85 | if gap > poll_interval.saturating_mul(self.gap_factor) { |
| 86 | self.reading = Some(reading); |
| 87 | self.changed_at = Some(now); |
| 88 | return Stillness::Restarted; |
| 89 | } |
| 90 | } |
| 91 | match &self.reading { |
| 92 | Some(prev) if *prev == reading => { |
| 93 | let since = now.saturating_duration_since(self.changed_at.unwrap_or(now)); |
| 94 | if since >= self.quiet { |
| 95 | Stillness::Still |
| 96 | } else { |
| 97 | Stillness::Settling(self.quiet - since) |
| 98 | } |
| 99 | }, |
| 100 | // No previous reading (the first poll), or the reading has changed. |
| 101 | _ => { |
| 102 | self.reading = Some(reading); |
| 103 | self.changed_at = Some(now); |
| 104 | Stillness::Moved |
| 105 | }, |
| 106 | } |
| 107 | } |
| 108 | |
| 109 | /// The reading last fed to [`Quiet::poll`], if any. |
| 110 | pub fn reading(&self) -> Option<&T> { |
| 111 | self.reading.as_ref() |
| 112 | } |
| 113 | |
| 114 | /// Forgets the reading and the window, so the next poll is a first poll: [`Stillness::Moved`], |
| 115 | /// with the quiet window beginning there. For a caller that knows what the guard cannot, such |
| 116 | /// as the machine having slept. |
| 117 | pub fn restart(&mut self) { |
| 118 | self.reading = None; |
| 119 | self.changed_at = None; |
| 120 | self.last_poll = None; |
| 121 | } |
| 122 | } |