1#![forbid(unsafe_code)]
2
3use 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
17pub trait CacheKey<W> {
19 fn cache_key(&self, widget: &W) -> Option<u64>;
21}
22
23#[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#[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#[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
53pub struct CachedWidget<W, K = NoCacheKey> {
57 inner: W,
58 key: K,
59}
60
61#[derive(Debug, Clone)]
63struct CachedBuffer {
64 buffer: Buffer,
65}
66
67#[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 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 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 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 pub fn inner(&self) -> &W {
118 &self.inner
119 }
120
121 pub fn inner_mut(&mut self) -> &mut W {
123 &mut self.inner
124 }
125
126 pub fn into_inner(self) -> W {
128 self.inner
129 }
130
131 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 pub fn new() -> Self {
145 Self::default()
146 }
147
148 pub fn mark_dirty(&mut self) {
150 self.dirty = true;
151 }
152
153 pub fn clear_cache(&mut self) {
155 self.cache = None;
156 }
157
158 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 #[must_use]
168 pub fn is_cached(&self) -> bool {
169 self.cache.is_some() && !self.dirty
170 }
171
172 #[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 let mut cache_frame = Frame::new(area.width, area.height, frame.pool);
221 self.inner.render(local_area, &mut cache_frame);
222 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 cached.render(Rect::new(0, 0, 3, 3), &mut frame, &mut state);
383 assert!(state.cache.is_some());
384
385 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 #[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 cached.render(area, &mut frame, &mut state);
572 assert!(state.cache.is_some());
573
574 cached.render(area, &mut frame, &mut state);
576 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}