1use 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
19const VERSION_SEPARATOR: char = '\u{1f}';
21
22#[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#[derive(Clone, Eq, PartialEq, Hash)]
34struct TileKey {
35 source: Arc<str>,
37 tile_index: u32,
39 overview_idx: Option<u16>,
41}
42
43impl TileKey {
44 fn new(source: &Arc<str>, tile_index: usize, overview_idx: Option<usize>) -> Self {
45 #[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
63pub 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 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 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
129pub(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
142pub(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
149pub 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
157pub 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
163pub 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#[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#[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
186pub 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
192pub 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
199pub fn invalidate_identity(identity: &str) -> usize {
202 TILE_CACHE.lock().remove_where(|source| source == identity)
203}
204
205pub fn clear() {
207 let mut cache = TILE_CACHE.lock();
208 cache.entries.clear();
209 cache.current_bytes = 0;
210}
211
212pub 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#[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 pub evictions: u64,
229}
230
231#[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#[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 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()); 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); 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}