Skip to main content

cogrs/
tile_cache.rs

1//! Process-wide cache of decoded (decompressed, f32) source tiles.
2//!
3//! Byte-bounded LRU: 512 MiB by default (`COGRS_TILE_CACHE_MB` overrides it at first use, or
4//! call [`set_capacity`]). Tiles are keyed by the *source identity*, the object's identifier plus
5//! its version token (see [`source_id`]), so an object that was replaced can never be served
6//! from tiles decoded from its predecessor. [`invalidate_source`] drops every tile of a source,
7//! whatever its version.
8//!
9//! Hit, miss and eviction counters are atomics outside the lock.
10
11use lru::LruCache;
12use parking_lot::Mutex;
13use std::path::Path;
14use std::sync::atomic::{AtomicU64, Ordering};
15use std::sync::{Arc, LazyLock};
16
17const DEFAULT_CAPACITY_BYTES: usize = 512 * 1024 * 1024;
18
19/// Separates the identifier from the version in a source identity.
20const VERSION_SEPARATOR: char = '\u{1f}';
21
22/// Source identity used as the tile-cache key: `identifier`, or `identifier` + separator +
23/// `version` for sources that report a version (ETag, modification time).
24#[must_use]
25pub fn source_id(identifier: &str, version: Option<&str>) -> Arc<str> {
26    match version {
27        Some(version) => format!("{identifier}{VERSION_SEPARATOR}{version}").into(),
28        None => identifier.into(),
29    }
30}
31
32/// Key for cached decompressed tiles
33#[derive(Clone, Eq, PartialEq, Hash)]
34struct TileKey {
35    /// Source identity ([`source_id`])
36    source: Arc<str>,
37    /// Tile index within the IFD
38    tile_index: u32,
39    /// Overview index (None = full resolution, Some(n) = overview n)
40    overview_idx: Option<u16>,
41}
42
43impl TileKey {
44    fn new(source: &Arc<str>, tile_index: usize, overview_idx: Option<usize>) -> Self {
45        // Casts are safe: tile counts and overview counts are typically small
46        #[allow(clippy::cast_possible_truncation)]
47        TileKey {
48            source: Arc::clone(source),
49            tile_index: tile_index as u32,
50            overview_idx: overview_idx.map(|i| {
51                #[allow(clippy::cast_possible_truncation)]
52                { i as u16 }
53            }),
54        }
55    }
56}
57
58struct CacheEntry {
59    data: Arc<Vec<f32>>,
60    size_bytes: usize,
61}
62
63/// The tile cache's entries and byte accounting (behind the process-wide lock).
64pub struct TileCache {
65    current_bytes: usize,
66    capacity_bytes: usize,
67    entries: LruCache<TileKey, CacheEntry>,
68}
69
70impl TileCache {
71    fn new(capacity_bytes: usize) -> Self {
72        TileCache { current_bytes: 0, capacity_bytes, entries: LruCache::unbounded() }
73    }
74
75    fn get(&mut self, key: &TileKey) -> Option<Arc<Vec<f32>>> {
76        self.entries.get(key).map(|entry| Arc::clone(&entry.data))
77    }
78
79    fn contains(&self, key: &TileKey) -> bool {
80        self.entries.contains(key)
81    }
82
83    /// Evict least recently used entries until `needed` more bytes fit.
84    fn make_room(&mut self, needed: usize) {
85        while self.current_bytes + needed > self.capacity_bytes {
86            let Some((_key, entry)) = self.entries.pop_lru() else { break };
87            self.current_bytes = self.current_bytes.saturating_sub(entry.size_bytes);
88            EVICTIONS.fetch_add(1, Ordering::Relaxed);
89        }
90    }
91
92    fn insert(&mut self, key: TileKey, data: Arc<Vec<f32>>, size_bytes: usize) {
93        if size_bytes > self.capacity_bytes {
94            return;
95        }
96        if let Some(old) = self.entries.pop(&key) {
97            self.current_bytes = self.current_bytes.saturating_sub(old.size_bytes);
98        }
99        self.make_room(size_bytes);
100        self.current_bytes = self.current_bytes.saturating_add(size_bytes);
101        self.entries.put(key, CacheEntry { data, size_bytes });
102    }
103
104    /// Remove every entry whose source identity satisfies `matches`.
105    fn remove_where(&mut self, matches: impl Fn(&str) -> bool) -> usize {
106        let doomed: Vec<TileKey> =
107            self.entries.iter().filter(|(key, _)| matches(&key.source)).map(|(key, _)| key.clone()).collect();
108        for key in &doomed {
109            if let Some(entry) = self.entries.pop(key) {
110                self.current_bytes = self.current_bytes.saturating_sub(entry.size_bytes);
111            }
112        }
113        doomed.len()
114    }
115}
116
117static HITS: AtomicU64 = AtomicU64::new(0);
118static MISSES: AtomicU64 = AtomicU64::new(0);
119static EVICTIONS: AtomicU64 = AtomicU64::new(0);
120
121static TILE_CACHE: LazyLock<Mutex<TileCache>> = LazyLock::new(|| {
122    let capacity = std::env::var("COGRS_TILE_CACHE_MB")
123        .ok()
124        .and_then(|mb| mb.trim().parse::<usize>().ok())
125        .map_or(DEFAULT_CAPACITY_BYTES, |mb| mb.saturating_mul(1024 * 1024));
126    Mutex::new(TileCache::new(capacity))
127});
128
129/// Get a cached tile by source identity ([`source_id`]), tile index, and optional overview index
130/// (`None` for full resolution, `Some(n)` for overview n).
131pub(crate) fn get_shared(source: &Arc<str>, tile_index: usize, overview_idx: Option<usize>) -> Option<Arc<Vec<f32>>> {
132    let key = TileKey::new(source, tile_index, overview_idx);
133    let found = TILE_CACHE.lock().get(&key);
134    if found.is_some() {
135        HITS.fetch_add(1, Ordering::Relaxed);
136    } else {
137        MISSES.fetch_add(1, Ordering::Relaxed);
138    }
139    found
140}
141
142/// Insert a decompressed tile under a source identity.
143pub(crate) fn insert_shared(source: &Arc<str>, tile_index: usize, overview_idx: Option<usize>, data: Arc<Vec<f32>>) {
144    let size_bytes = data.len() * std::mem::size_of::<f32>();
145    let key = TileKey::new(source, tile_index, overview_idx);
146    TILE_CACHE.lock().insert(key, data, size_bytes);
147}
148
149/// Get a cached tile by source identifier, tile index, and optional overview index
150/// - `source`: File path or URL identifying the COG (version-less identity)
151/// - `tile_index`: Tile index within the IFD
152/// - `overview_idx`: None for full resolution, Some(n) for overview n
153pub fn get(source: &str, tile_index: usize, overview_idx: Option<usize>) -> Option<Arc<Vec<f32>>> {
154    get_shared(&Arc::from(source), tile_index, overview_idx)
155}
156
157/// Check if a tile is cached
158pub fn contains(source: &str, tile_index: usize, overview_idx: Option<usize>) -> bool {
159    let key = TileKey::new(&Arc::from(source), tile_index, overview_idx);
160    TILE_CACHE.lock().contains(&key)
161}
162
163/// Insert a decompressed tile into the cache
164pub fn insert(source: &str, tile_index: usize, overview_idx: Option<usize>, data: Arc<Vec<f32>>) {
165    insert_shared(&Arc::from(source), tile_index, overview_idx, data);
166}
167
168// ============================================================================
169// Path-based API for tiff_chunked.rs and lzw_fallback.rs
170// ============================================================================
171
172/// Get cached tile by file path (used by tiff_chunked and lzw_fallback modules)
173#[must_use]
174pub fn get_by_path(path: &Path, index: usize) -> Option<Arc<Vec<f32>>> {
175    let source = path.to_string_lossy();
176    get(&source, index, None)
177}
178
179/// Check if tile is cached by file path
180#[must_use]
181pub fn contains_by_path(path: &Path, index: usize) -> bool {
182    let source = path.to_string_lossy();
183    contains(&source, index, None)
184}
185
186/// Insert tile into cache by file path
187pub fn insert_by_path(path: &Path, index: usize, data: Arc<Vec<f32>>) {
188    let source = path.to_string_lossy();
189    insert(&source, index, None, data);
190}
191
192/// Drop every cached tile of the source with this `identifier`, whatever its version. Returns
193/// the number of tiles removed.
194pub fn invalidate_source(identifier: &str) -> usize {
195    let versioned = format!("{identifier}{VERSION_SEPARATOR}");
196    TILE_CACHE.lock().remove_where(|source| source == identifier || source.starts_with(&versioned))
197}
198
199/// Drop the cached tiles of exactly one source identity ([`source_id`]): one version of a source,
200/// leaving its other versions alone. Returns the number of tiles removed.
201pub fn invalidate_identity(identity: &str) -> usize {
202    TILE_CACHE.lock().remove_where(|source| source == identity)
203}
204
205/// Drop every cached tile.
206pub fn clear() {
207    let mut cache = TILE_CACHE.lock();
208    cache.entries.clear();
209    cache.current_bytes = 0;
210}
211
212/// Set the capacity in bytes, evicting least recently used tiles if the cache is now over it.
213pub fn set_capacity(capacity_bytes: usize) {
214    let mut cache = TILE_CACHE.lock();
215    cache.capacity_bytes = capacity_bytes;
216    cache.make_room(0);
217}
218
219/// Point-in-time statistics of the tile cache.
220#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
221pub struct TileCacheStats {
222    pub entries: usize,
223    pub bytes: usize,
224    pub capacity_bytes: usize,
225    pub hits: u64,
226    pub misses: u64,
227    /// Tiles evicted to stay within the capacity.
228    pub evictions: u64,
229}
230
231/// Current statistics. Only the entry count and byte total take the cache lock briefly; the
232/// counters are atomics.
233#[must_use]
234pub fn snapshot() -> TileCacheStats {
235    let (entries, bytes, capacity_bytes) = {
236        let cache = TILE_CACHE.lock();
237        (cache.entries.len(), cache.current_bytes, cache.capacity_bytes)
238    };
239    TileCacheStats {
240        entries,
241        bytes,
242        capacity_bytes,
243        hits: HITS.load(Ordering::Relaxed),
244        misses: MISSES.load(Ordering::Relaxed),
245        evictions: EVICTIONS.load(Ordering::Relaxed),
246    }
247}
248
249/// Cache statistics: (`entry_count`, `current_bytes`, `capacity_bytes`, hits, misses)
250#[must_use]
251pub fn stats() -> (usize, usize, usize, u64, u64) {
252    let s = snapshot();
253    (s.entries, s.bytes, s.capacity_bytes, s.hits, s.misses)
254}
255
256#[cfg(test)]
257mod tests {
258    use super::*;
259
260    fn tile(len: usize) -> Arc<Vec<f32>> {
261        Arc::new(vec![1.0; len])
262    }
263
264    #[test]
265    fn versions_are_separate_identities() {
266        let (a, b) = (source_id("tc://obj", Some("\"v1\"")), source_id("tc://obj", Some("\"v2\"")));
267        insert_shared(&a, 0, None, tile(4));
268        assert!(get_shared(&a, 0, None).is_some());
269        assert!(get_shared(&b, 0, None).is_none(), "a new version must not see the old version's tiles");
270        assert!(get_shared(&source_id("tc://obj", None), 0, None).is_none());
271    }
272
273    #[test]
274    fn invalidate_source_removes_all_versions_and_only_that_source() {
275        let (v1, v2) = (source_id("tc://inv/a", Some("1")), source_id("tc://inv/a", Some("2")));
276        let other = source_id("tc://inv/ab", Some("1"));
277        for id in [&v1, &v2, &other] {
278            insert_shared(id, 3, Some(1), tile(8));
279        }
280        assert_eq!(invalidate_source("tc://inv/a"), 2);
281        assert!(get_shared(&v1, 3, Some(1)).is_none() && get_shared(&v2, 3, Some(1)).is_none());
282        assert!(get_shared(&other, 3, Some(1)).is_some(), "a source sharing the prefix is untouched");
283    }
284
285    #[test]
286    fn invalidate_identity_removes_one_version_only() {
287        let (v1, v2) = (source_id("tc://ident/a", Some("1")), source_id("tc://ident/a", Some("2")));
288        insert_shared(&v1, 0, None, tile(8));
289        insert_shared(&v2, 0, None, tile(8));
290        assert_eq!(invalidate_identity(&v1), 1);
291        assert!(get_shared(&v1, 0, None).is_none());
292        assert!(get_shared(&v2, 0, None).is_some());
293    }
294
295    #[test]
296    fn evicts_least_recently_used_by_bytes() {
297        let mut cache = TileCache::new(100 * 4);
298        let id: Arc<str> = "tc://evict".into();
299        let key = |i| TileKey::new(&id, i, None);
300        for i in 0..3 {
301            cache.insert(key(i), tile(40), 40 * 4);
302        }
303        // 40 + 40 fit, the third evicted the oldest
304        assert_eq!(cache.entries.len(), 2);
305        assert!(!cache.contains(&key(0)) && cache.contains(&key(1)) && cache.contains(&key(2)));
306        assert!(cache.get(&key(1)).is_some()); // 1 is now the most recent
307        cache.insert(key(3), tile(40), 40 * 4);
308        assert!(cache.contains(&key(1)) && !cache.contains(&key(2)));
309        cache.insert(key(9), tile(1000), 1000 * 4); // larger than the capacity: skipped
310        assert!(!cache.contains(&key(9)));
311        assert_eq!(cache.current_bytes, 2 * 40 * 4);
312    }
313
314    #[test]
315    fn counters_and_snapshot_track_hits_and_misses() {
316        let id = source_id("tc://counters", Some("x"));
317        let before = snapshot();
318        assert!(get_shared(&id, 0, None).is_none());
319        insert_shared(&id, 0, None, tile(2));
320        assert!(get_shared(&id, 0, None).is_some());
321        let after = snapshot();
322        assert!(after.misses > before.misses && after.hits > before.hits);
323        assert!(after.entries >= 1 && after.bytes >= 8);
324    }
325}