Oregami
Repositories/oxedyne/fe2o3

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
28use 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)]
36pub 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)]
49pub 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
57impl<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}