edamame 0.1.1

A fast TUI Markdown editor and viewer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

//! 200 ms quiet-window debouncer used by the watcher worker.
//!
//! Pure state machine over wall-clock instants — no I/O.  The worker
//! calls [`Debouncer::record`] on every incoming notify event and
//! consults [`Debouncer::deadline`] to compute the next channel
//! `recv_timeout`; when that timeout fires, [`Debouncer::fire_if_due`]
//! returns true and the worker performs a single disk read.
//!
//! Splitting the debouncer out keeps the timing logic testable
//! without standing up a notify backend.

use std::time::{Duration, Instant};

pub struct Debouncer {
    window: Duration,
    pending_since: Option<Instant>,
}

impl Debouncer {
    pub fn new(window: Duration) -> Self {
        Self {
            window,
            pending_since: None,
        }
    }

    /// Record that an event arrived at `now`.  Sliding window: a fresh
    /// event during an existing pending interval restarts the timer,
    /// so a rapid burst of events fires exactly once after the burst
    /// finishes.
    pub fn record(&mut self, now: Instant) {
        self.pending_since = Some(now);
    }

    /// The instant at which the pending fire is due, if any.  Used by
    /// the worker to set the channel `recv_timeout`.
    pub fn deadline(&self) -> Option<Instant> {
        self.pending_since.map(|t| t + self.window)
    }

    /// True when a fire is pending (regardless of whether the
    /// deadline has elapsed yet).
    #[allow(dead_code)] // used by tests; reserved for future use
    pub fn is_pending(&self) -> bool {
        self.pending_since.is_some()
    }

    /// If a fire is pending and `now` has reached the deadline,
    /// clear the pending state and return `true`.  Otherwise return
    /// `false` without mutating state.
    pub fn fire_if_due(&mut self, now: Instant) -> bool {
        let Some(deadline) = self.deadline() else {
            return false;
        };
        if now >= deadline {
            self.pending_since = None;
            true
        } else {
            false
        }
    }

    /// Drop any pending fire without firing.  Used when the worker
    /// performs a forced reconcile or unwatch.
    pub fn clear(&mut self) {
        self.pending_since = None;
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn window() -> Duration {
        Duration::from_millis(200)
    }

    #[test]
    fn fresh_debouncer_is_idle() {
        let d = Debouncer::new(window());
        assert!(!d.is_pending());
        assert!(d.deadline().is_none());
    }

    #[test]
    fn record_arms_the_deadline() {
        let mut d = Debouncer::new(window());
        let t0 = Instant::now();
        d.record(t0);
        assert!(d.is_pending());
        assert_eq!(d.deadline(), Some(t0 + window()));
    }

    #[test]
    fn fire_if_due_returns_false_before_deadline() {
        let mut d = Debouncer::new(window());
        let t0 = Instant::now();
        d.record(t0);
        assert!(!d.fire_if_due(t0 + Duration::from_millis(50)));
        assert!(d.is_pending(), "still pending below deadline");
    }

    #[test]
    fn fire_if_due_clears_state_at_deadline() {
        let mut d = Debouncer::new(window());
        let t0 = Instant::now();
        d.record(t0);
        assert!(d.fire_if_due(t0 + window()));
        assert!(!d.is_pending());
        assert!(d.deadline().is_none());
    }

    #[test]
    fn record_during_pending_extends_window() {
        // Sliding window: a burst of events keeps pushing the
        // deadline forward, so the fire only happens after the
        // burst finishes.
        let mut d = Debouncer::new(window());
        let t0 = Instant::now();
        d.record(t0);
        let t1 = t0 + Duration::from_millis(100);
        d.record(t1);
        // The original deadline has not yet elapsed, but the new one
        // is later — verify the slide.
        assert_eq!(d.deadline(), Some(t1 + window()));
        assert!(!d.fire_if_due(t0 + window()));
    }

    #[test]
    fn clear_discards_pending_state() {
        let mut d = Debouncer::new(window());
        d.record(Instant::now());
        d.clear();
        assert!(!d.is_pending());
        assert!(d.deadline().is_none());
    }

    #[test]
    fn fire_if_due_on_idle_is_a_noop() {
        let mut d = Debouncer::new(window());
        assert!(!d.fire_if_due(Instant::now()));
        assert!(!d.is_pending());
    }
}