Skip to main content

ftui_runtime/reactive/
batch.rs

1#![forbid(unsafe_code)]
2
3//! Batch update coalescing for `Observable` notifications.
4//!
5//! When multiple `Observable` values are updated in rapid succession,
6//! subscribers receive a notification for each change. In render-heavy
7//! scenarios this causes redundant intermediate renders. Batch coalescing
8//! defers all notifications until the batch scope exits, then fires each
9//! unique callback at most once.
10//!
11//! # Usage
12//!
13//! ```ignore
14//! use ftui_runtime::reactive::batch::BatchScope;
15//!
16//! let x = Observable::new(0);
17//! let y = Observable::new(0);
18//!
19//! {
20//!     let _batch = BatchScope::new();
21//!     x.set(1);  // notification deferred
22//!     y.set(2);  // notification deferred
23//!     x.set(3);  // notification deferred (coalesced with first x.set)
24//! }  // all notifications fire here, x subscribers called once with value 3
25//! ```
26//!
27//! # Invariants
28//!
29//! 1. Nested batches are supported: only the outermost scope triggers flush.
30//! 2. Within a batch, `Observable::get()` always returns the latest value
31//!    (values are updated immediately, only notifications are deferred).
32//! 3. After a batch exits, all subscribers see the final state, never an
33//!    intermediate state.
34//! 4. Flush calls deferred callbacks in the order they were first enqueued.
35//!
36//! # Failure Modes
37//!
38//! - **Callback panics during flush**: Remaining callbacks are still called.
39//!   The first panic is re-raised after all callbacks have been attempted.
40
41use ftui_core::with_panic_cleanup_suppressed;
42use std::cell::RefCell;
43use tracing::{info, info_span};
44use web_time::Instant;
45
46/// A deferred notification: a closure that fires a subscriber callback
47/// with the latest value.
48type DeferredNotify = Box<dyn FnOnce()>;
49
50/// Deferred callback entry optionally keyed for in-batch coalescing.
51struct DeferredEntry {
52    key: Option<usize>,
53    notify: DeferredNotify,
54}
55
56impl DeferredEntry {
57    fn unkeyed(notify: DeferredNotify) -> Self {
58        Self { key: None, notify }
59    }
60
61    fn keyed(key: usize, notify: DeferredNotify) -> Self {
62        Self {
63            key: Some(key),
64            notify,
65        }
66    }
67}
68
69/// Thread-local batch context.
70struct BatchContext {
71    /// Nesting depth. Only flush when this reaches 0.
72    depth: u32,
73    /// Queued notifications to fire on flush.
74    deferred: Vec<DeferredEntry>,
75    /// Number of source row updates coalesced into this batch.
76    rows_changed: u64,
77}
78
79thread_local! {
80    static BATCH_CTX: RefCell<Option<BatchContext>> = const { RefCell::new(None) };
81}
82
83/// Returns true if a batch is currently active on this thread.
84pub fn is_batching() -> bool {
85    BATCH_CTX.with(|ctx| ctx.borrow().is_some())
86}
87
88/// Enqueue a deferred notification to be fired when the current batch exits.
89///
90/// If no batch is active, the notification fires immediately.
91///
92/// Returns `true` if the notification was deferred, `false` if it fired
93/// immediately.
94pub fn defer_or_run(f: impl FnOnce() + 'static) -> bool {
95    BATCH_CTX.with(|ctx| {
96        let mut guard = ctx.borrow_mut();
97        if let Some(ref mut batch) = *guard {
98            batch.deferred.push(DeferredEntry::unkeyed(Box::new(f)));
99            true
100        } else {
101            drop(guard); // Release borrow before calling f.
102            f();
103            false
104        }
105    })
106}
107
108/// Enqueue a deferred notification keyed by `key`.
109///
110/// If the key already exists in the current batch, the previously queued
111/// callback is replaced so the latest callback wins while preserving the
112/// original enqueue order.
113pub fn defer_or_run_keyed(key: usize, f: impl FnOnce() + 'static) -> bool {
114    BATCH_CTX.with(|ctx| {
115        let mut guard = ctx.borrow_mut();
116        if let Some(ref mut batch) = *guard {
117            if let Some(entry) = batch
118                .deferred
119                .iter_mut()
120                .find(|entry| entry.key == Some(key))
121            {
122                entry.notify = Box::new(f);
123            } else {
124                batch.deferred.push(DeferredEntry::keyed(key, Box::new(f)));
125            }
126            true
127        } else {
128            drop(guard); // Release borrow before calling f.
129            f();
130            false
131        }
132    })
133}
134
135/// Record row-level changes while a batch is active.
136pub fn record_rows_changed(rows: u64) {
137    if rows == 0 {
138        return;
139    }
140    BATCH_CTX.with(|ctx| {
141        if let Some(ref mut batch) = *ctx.borrow_mut() {
142            batch.rows_changed = batch.rows_changed.saturating_add(rows);
143        }
144    });
145}
146
147/// Flush all deferred notifications. Called internally by `BatchScope::drop`.
148fn flush() {
149    let (rows_changed, deferred): (u64, Vec<DeferredNotify>) = BATCH_CTX.with(|ctx| {
150        let mut guard = ctx.borrow_mut();
151        if let Some(ref mut batch) = *guard {
152            let rows = batch.rows_changed;
153            batch.rows_changed = 0;
154            let deferred = std::mem::take(&mut batch.deferred)
155                .into_iter()
156                .map(|entry| entry.notify)
157                .collect();
158            (rows, deferred)
159        } else {
160            (0, Vec::new())
161        }
162    });
163
164    if deferred.is_empty() {
165        return;
166    }
167
168    let widgets_invalidated = deferred.len() as u64;
169    let propagation_start = Instant::now();
170    let _span = info_span!(
171        "bloodstream.delta",
172        rows_changed,
173        widgets_invalidated,
174        duration_us = tracing::field::Empty
175    )
176    .entered();
177
178    // Run all deferred notifications outside the borrow.
179    // If a callback panics, we still try to run the rest.
180    let mut first_panic: Option<Box<dyn std::any::Any + Send>> = None;
181    for notify in deferred {
182        let result = with_panic_cleanup_suppressed(|| {
183            std::panic::catch_unwind(std::panic::AssertUnwindSafe(notify))
184        });
185        if let Err(payload) = result
186            && first_panic.is_none()
187        {
188            first_panic = Some(payload);
189        }
190    }
191
192    let duration_us = propagation_start.elapsed().as_micros() as u64;
193    tracing::Span::current().record("duration_us", duration_us);
194    info!(
195        target: crate::telemetry_schema::TARGET_RUNTIME,
196        bloodstream_propagation_duration_us = duration_us,
197        rows_changed, widgets_invalidated, "bloodstream propagation duration histogram"
198    );
199
200    if let Some(payload) = first_panic {
201        std::panic::resume_unwind(payload);
202    }
203}
204
205/// RAII guard that begins a batch scope.
206///
207/// While a `BatchScope` is alive, all [`Observable`](super::Observable)
208/// notifications are deferred. When the outermost `BatchScope` drops,
209/// all deferred notifications fire.
210///
211/// Nested `BatchScope`s are supported — only the outermost one flushes.
212pub struct BatchScope {
213    /// Whether this scope is the outermost (responsible for flush).
214    is_root: bool,
215}
216
217impl BatchScope {
218    /// Begin a new batch scope.
219    ///
220    /// If already inside a batch, this increments the nesting depth.
221    #[must_use]
222    pub fn new() -> Self {
223        let is_root = BATCH_CTX.with(|ctx| {
224            let mut guard = ctx.borrow_mut();
225            match *guard {
226                Some(ref mut batch) => {
227                    batch.depth += 1;
228                    false
229                }
230                None => {
231                    *guard = Some(BatchContext {
232                        depth: 1,
233                        deferred: Vec::new(),
234                        rows_changed: 0,
235                    });
236                    true
237                }
238            }
239        });
240        Self { is_root }
241    }
242
243    /// Number of deferred notifications queued in the current batch.
244    #[must_use]
245    pub fn pending_count(&self) -> usize {
246        BATCH_CTX.with(|ctx| ctx.borrow().as_ref().map_or(0, |b| b.deferred.len()))
247    }
248}
249
250impl Default for BatchScope {
251    fn default() -> Self {
252        Self::new()
253    }
254}
255
256impl Drop for BatchScope {
257    fn drop(&mut self) {
258        let should_flush = BATCH_CTX.with(|ctx| {
259            let mut guard = ctx.borrow_mut();
260            if let Some(ref mut batch) = *guard {
261                batch.depth -= 1;
262                batch.depth == 0
263            } else {
264                false
265            }
266        });
267
268        if should_flush {
269            flush();
270            // Clear the context after flush.
271            BATCH_CTX.with(|ctx| {
272                *ctx.borrow_mut() = None;
273            });
274        }
275    }
276}
277
278impl std::fmt::Debug for BatchScope {
279    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
280        f.debug_struct("BatchScope")
281            .field("is_root", &self.is_root)
282            .field("pending", &self.pending_count())
283            .finish()
284    }
285}
286
287// ---------------------------------------------------------------------------
288// Tests
289// ---------------------------------------------------------------------------
290
291#[cfg(test)]
292mod tests {
293    use super::*;
294    use crate::reactive::Observable;
295    use std::cell::Cell;
296    use std::cell::RefCell;
297    use std::rc::Rc;
298
299    #[test]
300    fn batch_defers_notifications() {
301        let obs = Observable::new(0);
302        let count = Rc::new(Cell::new(0u32));
303        let count_clone = Rc::clone(&count);
304
305        let _sub = obs.subscribe(move |_| {
306            count_clone.set(count_clone.get() + 1);
307        });
308
309        {
310            let _batch = BatchScope::new();
311            obs.set(1);
312            obs.set(2);
313            obs.set(3);
314            // No notifications yet.
315            assert_eq!(count.get(), 0);
316        }
317        // All notifications fire on batch exit.
318        assert!(count.get() > 0);
319    }
320
321    #[test]
322    fn batch_values_updated_immediately() {
323        let obs = Observable::new(0);
324        {
325            let _batch = BatchScope::new();
326            obs.set(42);
327            // Value is updated even within batch.
328            assert_eq!(obs.get(), 42);
329        }
330    }
331
332    #[test]
333    fn nested_batch_only_outermost_flushes() {
334        let obs = Observable::new(0);
335        let count = Rc::new(Cell::new(0u32));
336        let count_clone = Rc::clone(&count);
337
338        let _sub = obs.subscribe(move |_| {
339            count_clone.set(count_clone.get() + 1);
340        });
341
342        {
343            let _outer = BatchScope::new();
344            obs.set(1);
345
346            {
347                let _inner = BatchScope::new();
348                obs.set(2);
349                // Inner batch exit doesn't flush.
350            }
351            assert_eq!(count.get(), 0);
352            obs.set(3);
353        }
354        // Only outer batch exit flushes.
355        assert!(count.get() > 0);
356    }
357
358    #[test]
359    fn no_batch_fires_immediately() {
360        let obs = Observable::new(0);
361        let count = Rc::new(Cell::new(0u32));
362        let count_clone = Rc::clone(&count);
363
364        let _sub = obs.subscribe(move |_| {
365            count_clone.set(count_clone.get() + 1);
366        });
367
368        obs.set(1);
369        assert_eq!(count.get(), 1);
370
371        obs.set(2);
372        assert_eq!(count.get(), 2);
373    }
374
375    #[test]
376    fn is_batching_flag() {
377        assert!(!is_batching());
378        {
379            let _batch = BatchScope::new();
380            assert!(is_batching());
381        }
382        assert!(!is_batching());
383    }
384
385    #[test]
386    fn pending_count() {
387        let obs = Observable::new(0);
388        let _sub = obs.subscribe(|_| {});
389
390        let batch = BatchScope::new();
391        assert_eq!(batch.pending_count(), 0);
392
393        obs.set(1);
394        // Each set enqueues a deferred notification.
395        assert!(batch.pending_count() > 0);
396    }
397
398    #[test]
399    fn defer_or_run_without_batch() {
400        let ran = Rc::new(Cell::new(false));
401        let ran_clone = Rc::clone(&ran);
402
403        let deferred = defer_or_run(move || ran_clone.set(true));
404        assert!(!deferred);
405        assert!(ran.get());
406    }
407
408    #[test]
409    fn defer_or_run_with_batch() {
410        let ran = Rc::new(Cell::new(false));
411        let ran_clone = Rc::clone(&ran);
412
413        {
414            let _batch = BatchScope::new();
415            let deferred = defer_or_run(move || ran_clone.set(true));
416            assert!(deferred);
417            assert!(!ran.get());
418        }
419        assert!(ran.get());
420    }
421
422    #[test]
423    fn defer_or_run_keyed_coalesces_to_latest_callback() {
424        let value = Rc::new(Cell::new(0u32));
425        let v1 = Rc::clone(&value);
426        let v2 = Rc::clone(&value);
427
428        let batch = BatchScope::new();
429        assert_eq!(batch.pending_count(), 0);
430
431        assert!(defer_or_run_keyed(7, move || v1.set(1)));
432        assert_eq!(batch.pending_count(), 1);
433        assert!(defer_or_run_keyed(7, move || v2.set(2)));
434        assert_eq!(batch.pending_count(), 1, "same key should be coalesced");
435        assert_eq!(value.get(), 0, "callback should remain deferred");
436        drop(batch);
437
438        assert_eq!(value.get(), 2, "latest keyed callback should run");
439    }
440
441    #[test]
442    fn defer_or_run_keyed_preserves_first_enqueue_order() {
443        let order = Rc::new(RefCell::new(Vec::new()));
444        let o1 = Rc::clone(&order);
445        let o2 = Rc::clone(&order);
446        let o3 = Rc::clone(&order);
447
448        {
449            let batch = BatchScope::new();
450            assert!(defer_or_run_keyed(1, move || o1
451                .borrow_mut()
452                .push("first-old")));
453            assert!(defer_or_run_keyed(2, move || o2
454                .borrow_mut()
455                .push("second")));
456            assert!(defer_or_run_keyed(1, move || o3
457                .borrow_mut()
458                .push("first-new")));
459            assert_eq!(batch.pending_count(), 2);
460        }
461
462        assert_eq!(
463            *order.borrow(),
464            vec!["first-new", "second"],
465            "replaced keyed callback should keep its original queue position"
466        );
467    }
468
469    #[test]
470    fn debug_format() {
471        let batch = BatchScope::new();
472        let dbg = format!("{:?}", batch);
473        assert!(dbg.contains("BatchScope"));
474        assert!(dbg.contains("is_root"));
475        drop(batch);
476    }
477
478    #[test]
479    fn multiple_observables_in_batch() {
480        let a = Observable::new(0);
481        let b = Observable::new(0);
482        let a_count = Rc::new(Cell::new(0u32));
483        let b_count = Rc::new(Cell::new(0u32));
484        let a_clone = Rc::clone(&a_count);
485        let b_clone = Rc::clone(&b_count);
486
487        let _sub_a = a.subscribe(move |_| a_clone.set(a_clone.get() + 1));
488        let _sub_b = b.subscribe(move |_| b_clone.set(b_clone.get() + 1));
489
490        {
491            let _batch = BatchScope::new();
492            a.set(1);
493            b.set(2);
494            a.set(3);
495            b.set(4);
496            assert_eq!(a_count.get(), 0);
497            assert_eq!(b_count.get(), 0);
498        }
499        assert!(a_count.get() > 0);
500        assert!(b_count.get() > 0);
501    }
502
503    #[test]
504    fn batch_scope_default_trait() {
505        let batch = BatchScope::default();
506        assert!(is_batching());
507        drop(batch);
508        assert!(!is_batching());
509    }
510
511    #[test]
512    fn triple_nested_batch() {
513        let obs = Observable::new(0);
514        let count = Rc::new(Cell::new(0u32));
515        let count_clone = Rc::clone(&count);
516
517        let _sub = obs.subscribe(move |_| {
518            count_clone.set(count_clone.get() + 1);
519        });
520
521        {
522            let _outer = BatchScope::new();
523            obs.set(1);
524            {
525                let _mid = BatchScope::new();
526                obs.set(2);
527                {
528                    let _inner = BatchScope::new();
529                    obs.set(3);
530                }
531                assert_eq!(count.get(), 0, "inner drop should not flush");
532            }
533            assert_eq!(count.get(), 0, "mid drop should not flush");
534        }
535        assert!(count.get() > 0, "outer drop should flush");
536    }
537
538    #[test]
539    fn empty_batch_no_panic() {
540        {
541            let _batch = BatchScope::new();
542            // No observable mutations
543        }
544        assert!(!is_batching());
545    }
546
547    #[test]
548    fn pending_count_zero_without_subscribers() {
549        let obs = Observable::new(0);
550        let batch = BatchScope::new();
551        obs.set(42);
552        // Without subscribers, set doesn't enqueue notifications
553        assert_eq!(batch.pending_count(), 0);
554        drop(batch);
555    }
556}