Skip to main content

ftui_widgets/
cached.rs

1#![forbid(unsafe_code)]
2
3//! Cached widget wrapper with manual invalidation and optional cache keys.
4
5use crate::{StatefulWidget, Widget};
6use ftui_core::geometry::Rect;
7use ftui_render::buffer::Buffer;
8use ftui_render::cell::Cell;
9use ftui_render::frame::Frame;
10use std::collections::hash_map::DefaultHasher;
11use std::hash::{Hash, Hasher};
12use std::mem::size_of;
13
14#[cfg(feature = "tracing")]
15use tracing::{debug, trace};
16
17/// Cache key strategy for a widget.
18pub trait CacheKey<W> {
19    /// Return a cache key for the widget, or `None` to disable key-based invalidation.
20    fn cache_key(&self, widget: &W) -> Option<u64>;
21}
22
23/// No cache key: invalidation is manual only.
24#[derive(Debug, Clone, Copy, Default)]
25pub struct NoCacheKey;
26
27impl<W> CacheKey<W> for NoCacheKey {
28    fn cache_key(&self, _widget: &W) -> Option<u64> {
29        None
30    }
31}
32
33/// Hash-based cache key using `std::hash::Hash`.
34#[derive(Debug, Clone, Copy, Default)]
35pub struct HashKey;
36
37impl<W: Hash> CacheKey<W> for HashKey {
38    fn cache_key(&self, widget: &W) -> Option<u64> {
39        Some(hash_value(widget))
40    }
41}
42
43/// Custom key function wrapper.
44#[derive(Debug, Clone, Copy)]
45pub struct FnKey<F>(pub F);
46
47impl<W, F: Fn(&W) -> u64> CacheKey<W> for FnKey<F> {
48    fn cache_key(&self, widget: &W) -> Option<u64> {
49        Some((self.0)(widget))
50    }
51}
52
53/// Cached widget wrapper.
54///
55/// Use with [`CachedWidgetState`] via the [`StatefulWidget`] trait.
56pub struct CachedWidget<W, K = NoCacheKey> {
57    inner: W,
58    key: K,
59}
60
61/// Internal cached buffer.
62#[derive(Debug, Clone)]
63struct CachedBuffer {
64    buffer: Buffer,
65}
66
67/// State for a cached widget.
68#[derive(Debug, Clone, Default)]
69pub struct CachedWidgetState {
70    cache: Option<CachedBuffer>,
71    last_area: Option<Rect>,
72    dirty: bool,
73    last_key: Option<u64>,
74}
75
76#[cfg(feature = "tracing")]
77#[derive(Debug, Clone, Copy)]
78enum CacheMissReason {
79    Empty,
80    Dirty,
81    AreaChanged,
82    KeyChanged,
83}
84
85impl<W> CachedWidget<W, NoCacheKey> {
86    /// Create a cached widget with manual invalidation.
87    pub fn new(widget: W) -> Self {
88        Self {
89            inner: widget,
90            key: NoCacheKey,
91        }
92    }
93}
94
95impl<W: Hash> CachedWidget<W, HashKey> {
96    /// Create a cached widget using `Hash` as the cache key.
97    pub fn with_hash(widget: W) -> Self {
98        Self {
99            inner: widget,
100            key: HashKey,
101        }
102    }
103}
104
105impl<W, F: Fn(&W) -> u64> CachedWidget<W, FnKey<F>> {
106    /// Create a cached widget with a custom cache key function.
107    pub fn with_key(widget: W, key_fn: F) -> Self {
108        Self {
109            inner: widget,
110            key: FnKey(key_fn),
111        }
112    }
113}
114
115impl<W, K> CachedWidget<W, K> {
116    /// Access the inner widget.
117    pub fn inner(&self) -> &W {
118        &self.inner
119    }
120
121    /// Mutable access to the inner widget.
122    pub fn inner_mut(&mut self) -> &mut W {
123        &mut self.inner
124    }
125
126    /// Consume the wrapper and return the inner widget.
127    pub fn into_inner(self) -> W {
128        self.inner
129    }
130
131    /// Mark the cache as dirty (forces a re-render on next draw).
132    pub fn mark_dirty(&self, state: &mut CachedWidgetState) {
133        state.mark_dirty();
134        #[cfg(feature = "tracing")]
135        debug!(
136            widget = std::any::type_name::<W>(),
137            "Cache invalidated via mark_dirty()"
138        );
139    }
140}
141
142impl CachedWidgetState {
143    /// Create a new empty cache state.
144    pub fn new() -> Self {
145        Self::default()
146    }
147
148    /// Mark the cache dirty without logging.
149    pub fn mark_dirty(&mut self) {
150        self.dirty = true;
151    }
152
153    /// Drop cached buffer to free memory.
154    pub fn clear_cache(&mut self) {
155        self.cache = None;
156    }
157
158    /// Approximate cache size in bytes.
159    pub fn cache_size_bytes(&self) -> usize {
160        self.cache
161            .as_ref()
162            .map(|cache| cache.buffer.len() * size_of::<Cell>())
163            .unwrap_or(0)
164    }
165
166    /// Check whether a buffer is currently cached and clean.
167    #[must_use]
168    pub fn is_cached(&self) -> bool {
169        self.cache.is_some() && !self.dirty
170    }
171
172    /// The cache key from the last render, if any.
173    #[must_use]
174    pub fn last_key(&self) -> Option<u64> {
175        self.last_key
176    }
177}
178
179impl<W: Widget, K: CacheKey<W>> StatefulWidget for CachedWidget<W, K> {
180    type State = CachedWidgetState;
181
182    fn render(&self, area: Rect, frame: &mut Frame, state: &mut CachedWidgetState) {
183        #[cfg(feature = "tracing")]
184        let _span = tracing::debug_span!(
185            "widget_render",
186            widget = "CachedWidget",
187            x = area.x,
188            y = area.y,
189            w = area.width,
190            h = area.height
191        )
192        .entered();
193
194        if area.is_empty() {
195            state.clear_cache();
196            state.last_area = Some(area);
197            return;
198        }
199
200        let key = self.key.cache_key(&self.inner);
201        let area_changed = state.last_area != Some(area);
202        let key_changed = key != state.last_key;
203
204        let needs_render = state.cache.is_none() || state.dirty || area_changed || key_changed;
205
206        #[cfg(feature = "tracing")]
207        let reason = if state.cache.is_none() {
208            CacheMissReason::Empty
209        } else if state.dirty {
210            CacheMissReason::Dirty
211        } else if area_changed {
212            CacheMissReason::AreaChanged
213        } else {
214            CacheMissReason::KeyChanged
215        };
216
217        if needs_render {
218            let local_area = Rect::from_size(area.width, area.height);
219            // Create a temporary frame for the inner widget
220            let mut cache_frame = Frame::new(area.width, area.height, frame.pool);
221            self.inner.render(local_area, &mut cache_frame);
222            // Extract the buffer from the frame for caching
223            state.cache = Some(CachedBuffer {
224                buffer: cache_frame.buffer,
225            });
226            state.last_area = Some(area);
227            state.dirty = false;
228            state.last_key = key;
229
230            #[cfg(feature = "tracing")]
231            debug!(
232                widget = std::any::type_name::<W>(),
233                reason = ?reason,
234                "Cache miss, re-rendering"
235            );
236        } else {
237            #[cfg(feature = "tracing")]
238            trace!(
239                widget = std::any::type_name::<W>(),
240                "Cache hit, using cached buffer"
241            );
242        }
243
244        if let Some(cache) = &state.cache {
245            let src_rect = Rect::from_size(area.width, area.height);
246            frame
247                .buffer
248                .copy_from(&cache.buffer, src_rect, area.x, area.y);
249        }
250    }
251}
252
253fn hash_value<T: Hash>(value: &T) -> u64 {
254    let mut hasher = DefaultHasher::new();
255    value.hash(&mut hasher);
256    hasher.finish()
257}
258
259#[cfg(test)]
260mod tests {
261    use super::*;
262    use ftui_render::grapheme_pool::GraphemePool;
263    use std::cell::Cell as CounterCell;
264    use std::rc::Rc;
265
266    #[derive(Debug, Clone)]
267    struct CountWidget {
268        count: Rc<CounterCell<u32>>,
269    }
270
271    impl Widget for CountWidget {
272        fn render(&self, area: Rect, frame: &mut Frame) {
273            self.count.set(self.count.get() + 1);
274            if !area.is_empty() {
275                frame.buffer.set(area.x, area.y, Cell::from_char('x'));
276            }
277        }
278    }
279
280    #[derive(Debug, Clone)]
281    struct KeyWidget {
282        count: Rc<CounterCell<u32>>,
283        key: Rc<CounterCell<u64>>,
284    }
285
286    impl Widget for KeyWidget {
287        fn render(&self, area: Rect, frame: &mut Frame) {
288            self.count.set(self.count.get() + 1);
289            if !area.is_empty() {
290                frame.buffer.set(area.x, area.y, Cell::from_char('k'));
291            }
292        }
293    }
294
295    #[test]
296    fn cache_hit_skips_rerender() {
297        let count = Rc::new(CounterCell::new(0));
298        let widget = CountWidget {
299            count: count.clone(),
300        };
301        let cached = CachedWidget::new(widget);
302        let mut state = CachedWidgetState::default();
303        let mut pool = GraphemePool::new();
304        let mut frame = Frame::new(5, 5, &mut pool);
305        let area = Rect::new(1, 1, 3, 3);
306
307        cached.render(area, &mut frame, &mut state);
308        cached.render(area, &mut frame, &mut state);
309
310        assert_eq!(count.get(), 1);
311    }
312
313    #[test]
314    fn area_change_forces_rerender() {
315        let count = Rc::new(CounterCell::new(0));
316        let widget = CountWidget {
317            count: count.clone(),
318        };
319        let cached = CachedWidget::new(widget);
320        let mut state = CachedWidgetState::default();
321        let mut pool = GraphemePool::new();
322        let mut frame = Frame::new(6, 6, &mut pool);
323
324        cached.render(Rect::new(0, 0, 3, 3), &mut frame, &mut state);
325        cached.render(Rect::new(1, 1, 3, 3), &mut frame, &mut state);
326
327        assert_eq!(count.get(), 2);
328    }
329
330    #[test]
331    fn mark_dirty_forces_rerender() {
332        let count = Rc::new(CounterCell::new(0));
333        let widget = CountWidget {
334            count: count.clone(),
335        };
336        let cached = CachedWidget::new(widget);
337        let mut state = CachedWidgetState::default();
338        let mut pool = GraphemePool::new();
339        let mut frame = Frame::new(5, 5, &mut pool);
340        let area = Rect::new(0, 0, 3, 3);
341
342        cached.render(area, &mut frame, &mut state);
343        cached.mark_dirty(&mut state);
344        cached.render(area, &mut frame, &mut state);
345
346        assert_eq!(count.get(), 2);
347    }
348
349    #[test]
350    fn key_change_forces_rerender() {
351        let count = Rc::new(CounterCell::new(0));
352        let key = Rc::new(CounterCell::new(1));
353        let widget = KeyWidget {
354            count: count.clone(),
355            key: key.clone(),
356        };
357        let cached = CachedWidget::with_key(widget, |w| w.key.get());
358        let mut state = CachedWidgetState::default();
359        let mut pool = GraphemePool::new();
360        let mut frame = Frame::new(5, 5, &mut pool);
361        let area = Rect::new(0, 0, 3, 3);
362
363        cached.render(area, &mut frame, &mut state);
364        key.set(2);
365        cached.render(area, &mut frame, &mut state);
366
367        assert_eq!(count.get(), 2);
368    }
369
370    #[test]
371    fn empty_area_clears_cache() {
372        let count = Rc::new(CounterCell::new(0));
373        let widget = CountWidget {
374            count: count.clone(),
375        };
376        let cached = CachedWidget::new(widget);
377        let mut state = CachedWidgetState::default();
378        let mut pool = GraphemePool::new();
379        let mut frame = Frame::new(5, 5, &mut pool);
380
381        // First render populates cache
382        cached.render(Rect::new(0, 0, 3, 3), &mut frame, &mut state);
383        assert!(state.cache.is_some());
384
385        // Empty area should clear cache
386        cached.render(Rect::new(0, 0, 0, 0), &mut frame, &mut state);
387        assert!(state.cache.is_none());
388        assert_eq!(count.get(), 1);
389    }
390
391    #[test]
392    fn cache_size_bytes_empty() {
393        let state = CachedWidgetState::new();
394        assert_eq!(state.cache_size_bytes(), 0);
395    }
396
397    #[test]
398    fn cache_size_bytes_after_render() {
399        let count = Rc::new(CounterCell::new(0));
400        let widget = CountWidget {
401            count: count.clone(),
402        };
403        let cached = CachedWidget::new(widget);
404        let mut state = CachedWidgetState::new();
405        let mut pool = GraphemePool::new();
406        let mut frame = Frame::new(5, 5, &mut pool);
407
408        cached.render(Rect::new(0, 0, 3, 3), &mut frame, &mut state);
409        assert!(state.cache_size_bytes() > 0);
410        assert_eq!(state.cache_size_bytes(), 9 * std::mem::size_of::<Cell>());
411    }
412
413    #[test]
414    fn clear_cache_drops_buffer() {
415        let count = Rc::new(CounterCell::new(0));
416        let widget = CountWidget {
417            count: count.clone(),
418        };
419        let cached = CachedWidget::new(widget);
420        let mut state = CachedWidgetState::new();
421        let mut pool = GraphemePool::new();
422        let mut frame = Frame::new(5, 5, &mut pool);
423
424        cached.render(Rect::new(0, 0, 3, 3), &mut frame, &mut state);
425        assert!(state.cache_size_bytes() > 0);
426
427        state.clear_cache();
428        assert_eq!(state.cache_size_bytes(), 0);
429    }
430
431    #[test]
432    fn mark_dirty_then_clear_on_render() {
433        let count = Rc::new(CounterCell::new(0));
434        let widget = CountWidget {
435            count: count.clone(),
436        };
437        let cached = CachedWidget::new(widget);
438        let mut state = CachedWidgetState::new();
439        let mut pool = GraphemePool::new();
440        let mut frame = Frame::new(5, 5, &mut pool);
441        let area = Rect::new(0, 0, 3, 3);
442
443        cached.render(area, &mut frame, &mut state);
444        assert_eq!(count.get(), 1);
445
446        state.mark_dirty();
447        assert!(state.dirty);
448
449        cached.render(area, &mut frame, &mut state);
450        assert_eq!(count.get(), 2);
451        assert!(!state.dirty);
452    }
453
454    #[test]
455    fn no_cache_key_returns_none() {
456        let key = NoCacheKey;
457        assert_eq!(CacheKey::<u32>::cache_key(&key, &42), None);
458    }
459
460    #[test]
461    fn hash_key_returns_some() {
462        let key = HashKey;
463        let result = CacheKey::<String>::cache_key(&key, &"hello".to_string());
464        assert!(result.is_some());
465    }
466
467    #[test]
468    fn hash_key_same_value_same_key() {
469        let key = HashKey;
470        let a = CacheKey::<u64>::cache_key(&key, &42);
471        let b = CacheKey::<u64>::cache_key(&key, &42);
472        assert_eq!(a, b);
473    }
474
475    #[test]
476    fn hash_key_different_value_different_key() {
477        let key = HashKey;
478        let a = CacheKey::<u64>::cache_key(&key, &1);
479        let b = CacheKey::<u64>::cache_key(&key, &2);
480        assert_ne!(a, b);
481    }
482
483    #[test]
484    fn fn_key_custom_function() {
485        let key = FnKey(|x: &u32| (*x as u64) * 100);
486        assert_eq!(CacheKey::<u32>::cache_key(&key, &5), Some(500));
487        assert_eq!(CacheKey::<u32>::cache_key(&key, &0), Some(0));
488    }
489
490    #[test]
491    fn inner_accessors() {
492        let count = Rc::new(CounterCell::new(0));
493        let widget = CountWidget {
494            count: count.clone(),
495        };
496        let mut cached = CachedWidget::new(widget);
497
498        assert_eq!(cached.inner().count.get(), 0);
499
500        cached.inner_mut().count.set(5);
501        assert_eq!(count.get(), 5);
502
503        let inner = cached.into_inner();
504        assert_eq!(inner.count.get(), 5);
505    }
506
507    #[test]
508    fn cached_content_matches_uncached() {
509        let count = Rc::new(CounterCell::new(0));
510        let widget = CountWidget {
511            count: count.clone(),
512        };
513        let cached = CachedWidget::new(widget.clone());
514        let mut state = CachedWidgetState::new();
515        let area = Rect::new(0, 0, 3, 3);
516
517        let mut pool_cached = GraphemePool::new();
518        let mut frame_cached = Frame::new(3, 3, &mut pool_cached);
519        cached.render(area, &mut frame_cached, &mut state);
520
521        let mut pool_direct = GraphemePool::new();
522        let mut frame_direct = Frame::new(3, 3, &mut pool_direct);
523        widget.render(area, &mut frame_direct);
524
525        assert_eq!(
526            frame_cached.buffer.get(0, 0).unwrap().content.as_char(),
527            frame_direct.buffer.get(0, 0).unwrap().content.as_char()
528        );
529    }
530
531    #[test]
532    fn multiple_cache_hits_never_rerender() {
533        let count = Rc::new(CounterCell::new(0));
534        let widget = CountWidget {
535            count: count.clone(),
536        };
537        let cached = CachedWidget::new(widget);
538        let mut state = CachedWidgetState::new();
539        let mut pool = GraphemePool::new();
540        let mut frame = Frame::new(5, 5, &mut pool);
541        let area = Rect::new(0, 0, 3, 3);
542
543        for _ in 0..10 {
544            cached.render(area, &mut frame, &mut state);
545        }
546        assert_eq!(count.get(), 1);
547    }
548
549    #[test]
550    fn with_hash_uses_hash_key() {
551        // with_hash requires W: Hash, so use a simple hashable wrapper
552        #[derive(Debug, Clone, Hash)]
553        struct HashableLabel(String);
554
555        impl Widget for HashableLabel {
556            fn render(&self, area: Rect, frame: &mut Frame) {
557                if !area.is_empty() {
558                    frame.buffer.set(area.x, area.y, Cell::from_char('h'));
559                }
560            }
561        }
562
563        let widget = HashableLabel("hello".to_string());
564        let cached = CachedWidget::with_hash(widget);
565        let mut state = CachedWidgetState::new();
566        let mut pool = GraphemePool::new();
567        let mut frame = Frame::new(5, 5, &mut pool);
568        let area = Rect::new(0, 0, 3, 3);
569
570        // First render: miss
571        cached.render(area, &mut frame, &mut state);
572        assert!(state.cache.is_some());
573
574        // Same hash => hit (no key change)
575        cached.render(area, &mut frame, &mut state);
576        // Verify the cache key was set
577        assert!(state.last_key.is_some());
578    }
579
580    #[test]
581    fn no_cache_key_default() {
582        let key = NoCacheKey;
583        assert_eq!(CacheKey::<u32>::cache_key(&key, &100), None);
584    }
585
586    #[test]
587    fn hash_key_default() {
588        let key = HashKey;
589        let result = CacheKey::<u32>::cache_key(&key, &42);
590        assert!(result.is_some());
591    }
592
593    #[test]
594    fn cached_widget_state_new_equals_default() {
595        let a = CachedWidgetState::new();
596        let b = CachedWidgetState::default();
597        assert_eq!(a.cache_size_bytes(), b.cache_size_bytes());
598        assert!(!a.dirty);
599        assert!(!b.dirty);
600    }
601
602    #[test]
603    fn same_key_no_rerender() {
604        let count = Rc::new(CounterCell::new(0));
605        let key = Rc::new(CounterCell::new(42));
606        let widget = KeyWidget {
607            count: count.clone(),
608            key: key.clone(),
609        };
610        let cached = CachedWidget::with_key(widget, |w| w.key.get());
611        let mut state = CachedWidgetState::new();
612        let mut pool = GraphemePool::new();
613        let mut frame = Frame::new(5, 5, &mut pool);
614        let area = Rect::new(0, 0, 3, 3);
615
616        cached.render(area, &mut frame, &mut state);
617        cached.render(area, &mut frame, &mut state);
618        cached.render(area, &mut frame, &mut state);
619
620        assert_eq!(count.get(), 1);
621    }
622}