parquet-tyfoom 0.8.0

data/ext/parquet-ruby-adapter/src/string_cache.rs

@@ -0,0 +1,115 @@
+use std::collections::HashSet;
+use triomphe::Arc;
+
+/// Default cap on distinct strings retained for reuse when `string_cache: true`.
+/// The cap is a deliberate memory bound (safety over hit rate): a high-cardinality
+/// column cannot grow the cache without limit. Once full, further distinct strings
+/// are not retained but already-cached values still reuse their shared storage.
+/// Callers can override it (`string_cache: <Integer>`). Reported statistics expose
+/// the cumulative miss count rather than pretending to know exact distinct
+/// cardinality after the bounded cache fills.
+pub const DEFAULT_STRING_CACHE_CAPACITY: usize = 100;
+
+/// Hard capacity ceiling for `string_cache:`. Each retained entry owns hash-table
+/// metadata plus one shared string allocation, so an explicit upper bound keeps a
+/// caller-provided capacity from becoming an eager unbounded allocation.
+pub const STRING_CACHE_CAPACITY_MAX: usize = 65_536;
+
+/// Per-value byte ceiling for retained cache entries. Oversized values still
+/// write correctly, but they are not retained for reuse across later rows.
+pub const STRING_CACHE_VALUE_BYTES_MAX: usize = 4096;
+
+/// Total retained UTF-8 bytes for cached string contents. This does not include
+/// hash-table metadata, which is separately bounded by `STRING_CACHE_CAPACITY_MAX`.
+pub const STRING_CACHE_RETAINED_BYTES_MAX: usize = 16 * 1024 * 1024;
+
+/// A cache for reusing string storage to reduce memory usage
+/// when there are many repeated strings
+#[derive(Debug)]
+pub struct StringCache {
+    capacity: usize,
+    entries: HashSet<Arc<str>>,
+    retained_bytes: usize,
+    hits: usize,
+    misses: usize,
+}
+
+impl StringCache {
+    /// Create a new string cache that retains at most `capacity` distinct
+    /// strings. The caller only constructs a cache when caching is enabled; a
+    /// disabled cache is represented by not creating one at all.
+    pub fn new(capacity: usize) -> Self {
+        debug_assert!(capacity > 0);
+        let capacity = capacity.min(STRING_CACHE_CAPACITY_MAX);
+
+        Self {
+            capacity,
+            entries: HashSet::with_capacity(capacity),
+            retained_bytes: 0,
+            hits: 0,
+            misses: 0,
+        }
+    }
+
+    /// Intern a string, returning shared storage for repeated values.
+    pub fn intern(&mut self, s: String) -> Arc<str> {
+        debug_assert!(self.entries.len() <= self.capacity);
+
+        if let Some(interned) = self.entries.get(s.as_str()) {
+            self.hits += 1;
+            return Arc::clone(interned);
+        }
+
+        let interned = Arc::<str>::from(s);
+        self.misses += 1;
+
+        let retained_bytes_next = self.retained_bytes.saturating_add(interned.len());
+        if self.entries.len() < self.capacity
+            && interned.len() <= STRING_CACHE_VALUE_BYTES_MAX
+            && retained_bytes_next <= STRING_CACHE_RETAINED_BYTES_MAX
+        {
+            self.retained_bytes = retained_bytes_next;
+            self.entries.insert(Arc::clone(&interned));
+        }
+
+        debug_assert!(self.entries.len() <= self.capacity);
+        debug_assert!(self.retained_bytes <= STRING_CACHE_RETAINED_BYTES_MAX);
+        interned
+    }
+
+    /// Get cache statistics
+    pub fn stats(&self) -> CacheStats {
+        debug_assert!(self.entries.len() <= self.capacity);
+
+        CacheStats {
+            size: self.entries.len(),
+            hits: self.hits,
+            misses: self.misses,
+            hit_rate: if self.hits + self.misses > 0 {
+                self.hits as f64 / (self.hits + self.misses) as f64
+            } else {
+                0.0
+            },
+        }
+    }
+
+    /// Clear the cache
+    pub fn clear(&mut self) {
+        self.entries.clear();
+        self.retained_bytes = 0;
+        self.hits = 0;
+        self.misses = 0;
+    }
+}
+
+#[derive(Debug)]
+pub struct CacheStats {
+    pub size: usize,
+    pub hits: usize,
+    pub misses: usize,
+    pub hit_rate: f64,
+}
+
+#[cfg(test)]
+#[path = "./string_cache_test.rs"]
+mod tests;

data/ext/parquet-ruby-adapter/src/string_cache_test.rs

@@ -0,0 +1,122 @@
+use super::{
+    StringCache, DEFAULT_STRING_CACHE_CAPACITY, STRING_CACHE_CAPACITY_MAX,
+    STRING_CACHE_RETAINED_BYTES_MAX, STRING_CACHE_VALUE_BYTES_MAX,
+};
+use triomphe::Arc;
+
+#[test]
+fn cache_reuses_storage_and_counts_hits() {
+    let mut cache = StringCache::new(DEFAULT_STRING_CACHE_CAPACITY);
+
+    let first = cache.intern("repeat".to_string());
+    let second = cache.intern("repeat".to_string());
+
+    assert!(Arc::ptr_eq(&first, &second));
+
+    let stats = cache.stats();
+    assert_eq!(stats.size, 1);
+    assert_eq!(stats.hits, 1);
+    assert_eq!(stats.misses, 1);
+    assert_eq!(stats.hit_rate, 0.5);
+}
+
+#[test]
+fn cache_stats_are_instance_local() {
+    let mut first_cache = StringCache::new(DEFAULT_STRING_CACHE_CAPACITY);
+    let mut second_cache = StringCache::new(DEFAULT_STRING_CACHE_CAPACITY);
+
+    let first_value = first_cache.intern("shared".to_string());
+    let first_value_again = first_cache.intern("shared".to_string());
+    let second_value = second_cache.intern("shared".to_string());
+
+    assert!(Arc::ptr_eq(&first_value, &first_value_again));
+    assert!(!Arc::ptr_eq(&first_value, &second_value));
+
+    let first_stats = first_cache.stats();
+    assert_eq!(first_stats.size, 1);
+    assert_eq!(first_stats.hits, 1);
+    assert_eq!(first_stats.misses, 1);
+
+    let second_stats = second_cache.stats();
+    assert_eq!(second_stats.size, 1);
+    assert_eq!(second_stats.hits, 0);
+    assert_eq!(second_stats.misses, 1);
+}
+
+#[test]
+fn cache_retention_is_bounded() {
+    let mut cache = StringCache::new(DEFAULT_STRING_CACHE_CAPACITY);
+
+    for index in 0..DEFAULT_STRING_CACHE_CAPACITY {
+        cache.intern(format!("value-{index}"));
+    }
+
+    let first_uncached = cache.intern("outside-bound".to_string());
+    let second_uncached = cache.intern("outside-bound".to_string());
+
+    assert!(!Arc::ptr_eq(&first_uncached, &second_uncached));
+
+    let stats = cache.stats();
+    assert_eq!(stats.size, DEFAULT_STRING_CACHE_CAPACITY);
+    assert_eq!(stats.hits, 0);
+    assert_eq!(stats.misses, DEFAULT_STRING_CACHE_CAPACITY + 2);
+}
+
+#[test]
+fn cache_capacity_has_a_hard_ceiling() {
+    let cache = StringCache::new(STRING_CACHE_CAPACITY_MAX + 1);
+
+    assert_eq!(cache.capacity, STRING_CACHE_CAPACITY_MAX);
+}
+
+#[test]
+fn oversized_values_are_not_retained() {
+    let mut cache = StringCache::new(DEFAULT_STRING_CACHE_CAPACITY);
+    let value = "x".repeat(STRING_CACHE_VALUE_BYTES_MAX + 1);
+
+    let first = cache.intern(value.clone());
+    let second = cache.intern(value);
+    let stats = cache.stats();
+
+    assert!(!Arc::ptr_eq(&first, &second));
+    assert_eq!(stats.size, 0);
+    assert_eq!(stats.hits, 0);
+    assert_eq!(stats.misses, 2);
+    assert_eq!(cache.retained_bytes, 0);
+}
+
+#[test]
+fn retained_bytes_are_bounded() {
+    let mut cache = StringCache::new(STRING_CACHE_CAPACITY_MAX);
+    let value_len = STRING_CACHE_VALUE_BYTES_MAX;
+    let retained_entry_count_max = STRING_CACHE_RETAINED_BYTES_MAX / value_len;
+
+    for index in 0..retained_entry_count_max {
+        cache.intern(format!("{index:08}-{}", "x".repeat(value_len - 9)));
+    }
+
+    assert_eq!(cache.retained_bytes, STRING_CACHE_RETAINED_BYTES_MAX);
+
+    let overflow = cache.intern("y".repeat(value_len));
+    let overflow_again = cache.intern("y".repeat(value_len));
+    let stats = cache.stats();
+
+    assert!(!Arc::ptr_eq(&overflow, &overflow_again));
+    assert_eq!(stats.size, retained_entry_count_max);
+    assert_eq!(cache.retained_bytes, STRING_CACHE_RETAINED_BYTES_MAX);
+}
+
+#[test]
+fn clear_removes_entries_and_resets_counts() {
+    let mut cache = StringCache::new(DEFAULT_STRING_CACHE_CAPACITY);
+
+    cache.intern("repeat".to_string());
+    cache.intern("repeat".to_string());
+    cache.clear();
+
+    let stats = cache.stats();
+    assert_eq!(stats.size, 0);
+    assert_eq!(stats.hits, 0);
+    assert_eq!(stats.misses, 0);
+    assert_eq!(stats.hit_rate, 0.0);
+}