Skip to main content

yse_model/
timing.rs

1//! Time-based stream operators: `debounce`, `throttle`, and `delay`.
2//!
3//! Operators take a [`Timer`] that runs one-shot tasks on the graph's thread
4//! (the GUI thread in a Qt application). [`ManualTimer`] drives them
5//! deterministically in tests.
6
7use crate::EventStream;
8use crate::graph::{Node, NodeCommon, NodeKind, TxState, schedule_node};
9use std::any::Any;
10use std::cell::{Cell, RefCell};
11use std::collections::VecDeque;
12use std::marker::PhantomData;
13use std::rc::{Rc, Weak};
14use std::time::Duration;
15
16/// A source of one-shot delayed tasks. Tasks must run on the thread that owns
17/// the reactive graph.
18pub trait Timer {
19    /// Run `task` once after `delay`, on the graph's thread.
20    fn schedule_after(&self, delay: Duration, task: Box<dyn FnOnce()>);
21}
22
23/// A test [`Timer`] that queues tasks until the test fires them.
24#[derive(Default)]
25pub struct ManualTimer {
26    queue: RefCell<VecDeque<(Duration, Box<dyn FnOnce()>)>>,
27}
28
29impl ManualTimer {
30    /// Create an empty timer.
31    pub fn new() -> Self {
32        Self::default()
33    }
34
35    /// Number of queued tasks.
36    pub fn pending(&self) -> usize {
37        self.queue.borrow().len()
38    }
39
40    /// Run the oldest queued task.
41    pub fn fire_next(&self) {
42        let task = self.queue.borrow_mut().pop_front().map(|(_, task)| task);
43        if let Some(task) = task {
44            task();
45        }
46    }
47}
48
49impl Timer for ManualTimer {
50    fn schedule_after(&self, delay: Duration, task: Box<dyn FnOnce()>) {
51        self.queue.borrow_mut().push_back((delay, task));
52    }
53}
54
55struct DebounceNode<T> {
56    common: NodeCommon,
57    timer: Rc<dyn Timer>,
58    window: Duration,
59    generation: Cell<u64>,
60    timer_fired: Cell<bool>,
61    pending: RefCell<Option<Rc<dyn Any>>>,
62    self_weak: Weak<Self>,
63    _marker: PhantomData<T>,
64}
65
66impl<T: 'static> DebounceNode<T> {
67    fn new(timer: Rc<dyn Timer>, window: Duration) -> Rc<Self> {
68        Rc::new_cyclic(|self_weak| Self {
69            common: NodeCommon::new(NodeKind::Stream),
70            timer,
71            window,
72            generation: Cell::new(0),
73            timer_fired: Cell::new(false),
74            pending: RefCell::new(None),
75            self_weak: self_weak.clone(),
76            _marker: PhantomData,
77        })
78    }
79
80    fn on_timer(&self, generation: u64) {
81        if generation != self.generation.get() {
82            return; // superseded by a newer event
83        }
84        self.timer_fired.set(true);
85        let node: Rc<dyn Node> = self
86            .self_weak
87            .upgrade()
88            .expect("debounce node must be alive while its timer fires");
89        crate::transaction(|| schedule_node(node));
90    }
91
92    fn arm(&self) {
93        let generation = self.generation.get() + 1;
94        self.generation.set(generation);
95        let weak = self.self_weak.clone();
96        let window = self.window;
97        let timer = self.timer.clone();
98        timer.schedule_after(
99            window,
100            Box::new(move || {
101                if let Some(node) = weak.upgrade() {
102                    node.on_timer(generation);
103                }
104            }),
105        );
106    }
107}
108
109impl<T: 'static> Node for DebounceNode<T> {
110    fn common(&self) -> &NodeCommon {
111        &self.common
112    }
113
114    fn process(&self, _tx: &TxState) -> Vec<Rc<dyn Any>> {
115        if self.timer_fired.take() {
116            return match self.pending.borrow_mut().take() {
117                Some(event) => vec![event],
118                None => Vec::new(),
119            };
120        }
121        let events = self.take_incoming();
122        if let Some(last) = events.into_iter().last() {
123            *self.pending.borrow_mut() = Some(last);
124            self.arm();
125        }
126        Vec::new()
127    }
128}
129
130struct ThrottleNode<T> {
131    common: NodeCommon,
132    timer: Rc<dyn Timer>,
133    window: Duration,
134    generation: Cell<u64>,
135    timer_fired: Cell<bool>,
136    in_window: Cell<bool>,
137    trailing: RefCell<Option<Rc<dyn Any>>>,
138    self_weak: Weak<Self>,
139    _marker: PhantomData<T>,
140}
141
142impl<T: 'static> ThrottleNode<T> {
143    fn new(timer: Rc<dyn Timer>, window: Duration) -> Rc<Self> {
144        Rc::new_cyclic(|self_weak| Self {
145            common: NodeCommon::new(NodeKind::Stream),
146            timer,
147            window,
148            generation: Cell::new(0),
149            timer_fired: Cell::new(false),
150            in_window: Cell::new(false),
151            trailing: RefCell::new(None),
152            self_weak: self_weak.clone(),
153            _marker: PhantomData,
154        })
155    }
156
157    fn on_timer(&self, generation: u64) {
158        if generation != self.generation.get() {
159            return;
160        }
161        self.timer_fired.set(true);
162        let node: Rc<dyn Node> = self
163            .self_weak
164            .upgrade()
165            .expect("throttle node must be alive while its timer fires");
166        crate::transaction(|| schedule_node(node));
167    }
168
169    fn arm(&self) {
170        let generation = self.generation.get() + 1;
171        self.generation.set(generation);
172        let weak = self.self_weak.clone();
173        let window = self.window;
174        let timer = self.timer.clone();
175        timer.schedule_after(
176            window,
177            Box::new(move || {
178                if let Some(node) = weak.upgrade() {
179                    node.on_timer(generation);
180                }
181            }),
182        );
183    }
184}
185
186impl<T: 'static> Node for ThrottleNode<T> {
187    fn common(&self) -> &NodeCommon {
188        &self.common
189    }
190
191    fn process(&self, _tx: &TxState) -> Vec<Rc<dyn Any>> {
192        let mut outputs = Vec::new();
193        if self.timer_fired.take() {
194            // End of the window: emit the trailing event if one arrived, then
195            // open the gate so the next event leads a fresh window.
196            if let Some(event) = self.trailing.borrow_mut().take() {
197                outputs.push(event);
198            }
199            self.in_window.set(false);
200            return outputs;
201        }
202        for event in self.take_incoming() {
203            if self.in_window.get() {
204                *self.trailing.borrow_mut() = Some(event);
205            } else {
206                self.in_window.set(true);
207                self.arm();
208                outputs.push(event); // leading edge
209            }
210        }
211        outputs
212    }
213}
214
215struct DelayNode<T> {
216    common: NodeCommon,
217    timer: Rc<dyn Timer>,
218    window: Duration,
219    generation: Cell<u64>,
220    timer_fired: Cell<bool>,
221    timer_pending: Cell<bool>,
222    queue: RefCell<VecDeque<Rc<dyn Any>>>,
223    self_weak: Weak<Self>,
224    _marker: PhantomData<T>,
225}
226
227impl<T: 'static> DelayNode<T> {
228    fn new(timer: Rc<dyn Timer>, window: Duration) -> Rc<Self> {
229        Rc::new_cyclic(|self_weak| Self {
230            common: NodeCommon::new(NodeKind::Stream),
231            timer,
232            window,
233            generation: Cell::new(0),
234            timer_fired: Cell::new(false),
235            timer_pending: Cell::new(false),
236            queue: RefCell::new(VecDeque::new()),
237            self_weak: self_weak.clone(),
238            _marker: PhantomData,
239        })
240    }
241
242    fn on_timer(&self, generation: u64) {
243        if generation != self.generation.get() {
244            return;
245        }
246        self.timer_fired.set(true);
247        let node: Rc<dyn Node> = self
248            .self_weak
249            .upgrade()
250            .expect("delay node must be alive while its timer fires");
251        crate::transaction(|| schedule_node(node));
252    }
253
254    fn arm(&self) {
255        let generation = self.generation.get() + 1;
256        self.generation.set(generation);
257        self.timer_pending.set(true);
258        let weak = self.self_weak.clone();
259        let window = self.window;
260        let timer = self.timer.clone();
261        timer.schedule_after(
262            window,
263            Box::new(move || {
264                if let Some(node) = weak.upgrade() {
265                    node.on_timer(generation);
266                }
267            }),
268        );
269    }
270}
271
272impl<T: 'static> Node for DelayNode<T> {
273    fn common(&self) -> &NodeCommon {
274        &self.common
275    }
276
277    fn process(&self, _tx: &TxState) -> Vec<Rc<dyn Any>> {
278        if self.timer_fired.take() {
279            self.timer_pending.set(false);
280            let mut outputs = Vec::new();
281            let event = self.queue.borrow_mut().pop_front();
282            if let Some(event) = event {
283                outputs.push(event);
284                if !self.queue.borrow().is_empty() {
285                    self.arm();
286                }
287            }
288            return outputs;
289        }
290        let events = self.take_incoming();
291        if !events.is_empty() {
292            let mut queue = self.queue.borrow_mut();
293            for event in events {
294                queue.push_back(event);
295            }
296            if !self.timer_pending.get() {
297                self.arm();
298            }
299        }
300        Vec::new()
301    }
302}
303
304impl<T> EventStream<T>
305where
306    T: 'static,
307{
308    /// Emit only after the stream has been quiet for `window`.
309    ///
310    /// Each event restarts the window; when it elapses without a newer event,
311    /// the latest event is emitted. Superseded timer firings are no-ops.
312    pub fn debounce(&self, timer: Rc<dyn Timer>, window: Duration) -> EventStream<T> {
313        let node = DebounceNode::<T>::new(timer, window);
314        let node_any: Rc<dyn Node> = node.clone();
315        crate::graph::connect(self.node.clone(), node_any.clone());
316        EventStream::new(node_any)
317    }
318
319    /// Emit at most one event per `window`: the first event immediately
320    /// (leading edge) and the last event of the window when it elapses
321    /// (trailing edge).
322    pub fn throttle(&self, timer: Rc<dyn Timer>, window: Duration) -> EventStream<T> {
323        let node = ThrottleNode::<T>::new(timer, window);
324        let node_any: Rc<dyn Node> = node.clone();
325        crate::graph::connect(self.node.clone(), node_any.clone());
326        EventStream::new(node_any)
327    }
328
329    /// Emit every event in order, each at least `window` after it arrived.
330    pub fn delay(&self, timer: Rc<dyn Timer>, window: Duration) -> EventStream<T> {
331        let node = DelayNode::<T>::new(timer, window);
332        let node_any: Rc<dyn Node> = node.clone();
333        crate::graph::connect(self.node.clone(), node_any.clone());
334        EventStream::new(node_any)
335    }
336}