typf_core/

shaping_cache.rs

//! Backend-agnostic shaping cache
//!
//! Shared cache implementation for text shaping results. Used by HarfBuzz-based
//! shapers to avoid expensive reshaping operations.
//!
//! This module was extracted from duplicated code in typf-shape-hb and
//! typf-shape-icu-hb to provide a single source of truth.

// this_file: crates/typf-core/src/shaping_cache.rs

use std::collections::hash_map::DefaultHasher;
use std::hash::{Hash, Hasher};
use std::sync::{Arc, RwLock};

use crate::cache::MultiLevelCache;
use crate::cache_config;
use crate::types::ShapingResult;

/// Key for caching shaping results
///
/// Uniquely identifies a shaping operation by its inputs:
/// text content, font identity, size, locale settings, OpenType features,
/// and variable font axis coordinates.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct ShapingCacheKey {
    /// Text content
    pub text: String,
    /// Name of the shaper/backend
    pub backend: String,
    /// Font identifier (hash of font data)
    pub font_id: u64,
    /// Font size in points (stored as u32: size * 100 for hash stability)
    pub size: u32,
    /// Language code (e.g., "en", "ar", "zh")
    pub language: Option<String>,
    /// Script tag (e.g., "latn", "arab", "hans")
    pub script: Option<String>,
    /// Enabled OpenType features with their values
    pub features: Vec<(String, u32)>,
    /// Variable font axis coordinates (stored as i32: value * 100 for hash stability)
    pub variations: Vec<(String, i32)>,
}

impl ShapingCacheKey {
    /// Create a new cache key from shaping inputs
    ///
    /// The font data is hashed to create a stable identifier that doesn't
    /// require keeping the full font data in memory for cache lookups.
    ///
    /// Variable font coordinates are included in the key to ensure different
    /// axis settings (e.g., wght=400 vs wght=700) produce different cache entries.
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        text: impl Into<String>,
        backend: impl Into<String>,
        font_data: &[u8],
        size: f32,
        language: Option<String>,
        script: Option<String>,
        features: Vec<(String, u32)>,
        variations: Vec<(String, f32)>,
    ) -> Self {
        // Hash the font data for the font_id
        let mut hasher = DefaultHasher::new();
        font_data.hash(&mut hasher);
        let font_id = hasher.finish();

        // Convert variations to integer representation for hash stability
        let variations_int: Vec<(String, i32)> = variations
            .into_iter()
            .map(|(tag, val)| (tag, (val * 100.0) as i32))
            .collect();

        Self {
            text: text.into(),
            backend: backend.into(),
            font_id,
            size: (size * 100.0) as u32, // Store as integer for stability
            language,
            script,
            features,
            variations: variations_int,
        }
    }
}

/// Cache for shaping results
///
/// Uses a two-level cache (L1 hot cache + L2 LRU cache) for optimal
/// performance across different access patterns.
pub struct ShapingCache {
    cache: MultiLevelCache<ShapingCacheKey, ShapingResult>,
}

impl std::fmt::Debug for ShapingCache {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ShapingCache")
            .field("cache", &self.cache)
            .finish()
    }
}

impl ShapingCache {
    /// Create a new shaping cache with default capacities
    ///
    /// L1 (hot cache): 100 entries for frequently accessed results
    /// L2 (LRU cache): 500 entries for less frequent access
    pub fn new() -> Self {
        Self {
            cache: MultiLevelCache::new(100, 500),
        }
    }

    /// Create a shaping cache with custom capacities
    pub fn with_capacity(l1_size: usize, l2_size: usize) -> Self {
        Self {
            cache: MultiLevelCache::new(l1_size, l2_size),
        }
    }

    /// Get a cached shaping result
    ///
    /// Returns `Some(result)` if the key exists in either cache level,
    /// `None` if not found or if caching is globally disabled.
    pub fn get(&self, key: &ShapingCacheKey) -> Option<ShapingResult> {
        if !cache_config::is_caching_enabled() {
            return None;
        }
        self.cache.get(key)
    }

    /// Insert a shaping result into the cache
    ///
    /// The result is stored in both L1 and L2 caches for maximum availability.
    /// Does nothing if caching is globally disabled.
    pub fn insert(&self, key: ShapingCacheKey, result: ShapingResult) {
        if !cache_config::is_caching_enabled() {
            return;
        }
        self.cache.insert(key, result);
    }

    /// Get the current cache hit rate (0.0 to 1.0)
    pub fn hit_rate(&self) -> f64 {
        self.cache.hit_rate()
    }

    /// Get cache statistics
    pub fn stats(&self) -> CacheStats {
        let metrics = self.cache.metrics();
        let total = metrics.l1_hits + metrics.l2_hits + metrics.misses;
        CacheStats {
            hits: (metrics.l1_hits + metrics.l2_hits) as usize,
            misses: metrics.misses as usize,
            evictions: 0, // Not tracked in current implementation
            hit_rate: if total > 0 {
                (metrics.l1_hits + metrics.l2_hits) as f64 / total as f64
            } else {
                0.0
            },
        }
    }
}

impl Default for ShapingCache {
    fn default() -> Self {
        Self::new()
    }
}

/// Cache statistics
#[derive(Debug, Clone)]
pub struct CacheStats {
    pub hits: usize,
    pub misses: usize,
    pub evictions: usize,
    pub hit_rate: f64,
}

/// Thread-safe shaping cache wrapper
pub type SharedShapingCache = Arc<RwLock<ShapingCache>>;

#[cfg(test)]
mod tests {
    use super::*;
    use crate::types::{Direction, PositionedGlyph};

    #[test]
    fn test_cache_key_creation() {
        let key = ShapingCacheKey::new(
            "Hello",
            "hb",
            b"font_data",
            16.0,
            Some("en".to_string()),
            Some("latn".to_string()),
            vec![("liga".to_string(), 1)],
            vec![("wght".to_string(), 700.0)],
        );

        assert_eq!(key.text, "Hello");
        assert_eq!(key.size, 1600); // 16.0 * 100
        assert_eq!(key.language, Some("en".to_string()));
        assert_eq!(key.variations, vec![("wght".to_string(), 70000)]); // 700.0 * 100
    }

    #[test]
    fn test_cache_insert_and_get() {
        let _guard = crate::cache_config::scoped_caching_enabled(true);

        let cache = ShapingCache::new();

        let key = ShapingCacheKey::new("Test", "hb", b"font", 12.0, None, None, vec![], vec![]);

        let result = ShapingResult {
            glyphs: vec![PositionedGlyph {
                id: 1,
                x: 0.0,
                y: 0.0,
                advance: 10.0,
                cluster: 0,
            }],
            advance_width: 10.0,
            advance_height: 12.0,
            direction: Direction::LeftToRight,
        };

        cache.insert(key.clone(), result.clone());
        let cached = match cache.get(&key) {
            Some(cached) => cached,
            None => unreachable!("cache should return inserted value"),
        };
        assert_eq!(cached.glyphs.len(), 1);
    }

    #[test]
    fn test_cache_miss() {
        let cache = ShapingCache::new();

        let key = ShapingCacheKey::new("Missing", "hb", b"font", 16.0, None, None, vec![], vec![]);
        assert!(cache.get(&key).is_none());
    }

    #[test]
    fn test_cache_stats() {
        let _guard = crate::cache_config::scoped_caching_enabled(true);

        let cache = ShapingCache::new();

        let key = ShapingCacheKey::new("Text", "hb", b"font", 16.0, None, None, vec![], vec![]);
        let result = ShapingResult {
            glyphs: vec![],
            advance_width: 0.0,
            advance_height: 16.0,
            direction: Direction::LeftToRight,
        };

        // Miss
        cache.get(&key);

        // Insert
        cache.insert(key.clone(), result);

        // Hit
        cache.get(&key);
        cache.get(&key);

        let stats = cache.stats();

        // Stats track hits and misses
        assert!(stats.hit_rate >= 0.0);
    }

    #[test]
    fn test_different_keys() {
        let key1 = ShapingCacheKey::new("Hello", "hb", b"font1", 16.0, None, None, vec![], vec![]);
        let key2 = ShapingCacheKey::new("Hello", "hb", b"font2", 16.0, None, None, vec![], vec![]);
        let key3 = ShapingCacheKey::new("World", "hb", b"font1", 16.0, None, None, vec![], vec![]);

        // Different font data should produce different keys
        assert_ne!(key1, key2);

        // Different text should produce different keys
        assert_ne!(key1, key3);
    }

    #[test]
    fn test_different_variations_produce_different_keys() {
        // Same font, same text, but different wght values
        let key_400 = ShapingCacheKey::new(
            "Test",
            "hb",
            b"font",
            16.0,
            None,
            None,
            vec![],
            vec![("wght".to_string(), 400.0)],
        );
        let key_700 = ShapingCacheKey::new(
            "Test",
            "hb",
            b"font",
            16.0,
            None,
            None,
            vec![],
            vec![("wght".to_string(), 700.0)],
        );
        let key_no_var =
            ShapingCacheKey::new("Test", "hb", b"font", 16.0, None, None, vec![], vec![]);

        // Different variations should produce different keys
        assert_ne!(
            key_400, key_700,
            "wght=400 and wght=700 should have different cache keys"
        );
        assert_ne!(
            key_400, key_no_var,
            "wght=400 and no variations should have different keys"
        );
    }
}