ftui_runtime/reactive/
batch.rs1#![forbid(unsafe_code)]
2
3use ftui_core::with_panic_cleanup_suppressed;
42use std::cell::RefCell;
43use tracing::{info, info_span};
44use web_time::Instant;
45
46type DeferredNotify = Box<dyn FnOnce()>;
49
50struct 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
69struct BatchContext {
71 depth: u32,
73 deferred: Vec<DeferredEntry>,
75 rows_changed: u64,
77}
78
79thread_local! {
80 static BATCH_CTX: RefCell<Option<BatchContext>> = const { RefCell::new(None) };
81}
82
83pub fn is_batching() -> bool {
85 BATCH_CTX.with(|ctx| ctx.borrow().is_some())
86}
87
88pub 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); f();
103 false
104 }
105 })
106}
107
108pub 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); f();
130 false
131 }
132 })
133}
134
135pub 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
147fn 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 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
205pub struct BatchScope {
213 is_root: bool,
215}
216
217impl BatchScope {
218 #[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 #[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 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#[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 assert_eq!(count.get(), 0);
316 }
317 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 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 }
351 assert_eq!(count.get(), 0);
352 obs.set(3);
353 }
354 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 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 }
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 assert_eq!(batch.pending_count(), 0);
554 drop(batch);
555 }
556}