//! Caches of what effects read from files named by a parameter (a LUT, an OCIO transform file, an //! OCIO config), keyed by the parameter text and checked against the files each result was read //! from (#3493, #3538). //! //! A cached result remembers every file its load read, with the file's size and modification time //! (its stamp) taken before reading, including the files a nested cached load read (a config's //! `FileTransform` LUTs) and files looked for but missing. Each lookup stamps those files again //! (one `metadata` call each) and loads again once one moved, so a file edited, created, deleted or //! repaired on disk is followed. Inline text reads no file and is its own content. An edit that keeps //! both the size and the modification time can't be told apart. //! //! Every file read is also followed by [`check_lut_files`], and [`lut_generation`] moves when one is //! found changed: the viewers and frame caches drop the frames made before. use std::cell::RefCell; use std::collections::{HashMap, HashSet}; use std::sync::atomic::{AtomicU64, Ordering}; use std::sync::{Mutex, MutexGuard, OnceLock, PoisonError}; use std::time::SystemTime; /// A file's size and modification time when it was read (`None`: missing, or a file that could /// not be described). A file whose stamp moved is read again. pub(crate) type FileStamp = Option<(u64, Option)>; /// The files a load read and their stamps. type Files = Vec<(String, FileStamp)>; /// At most this many files are followed by [`check_lut_files`]; the least recently read go first. const MAX_FOLLOWED_FILES: usize = 1024; /// One cached result and what it was read from. struct Entry { files: Files, value: V, used: u64, /// The result's size estimate and the parameter text, counted against the cache's byte bound. bytes: usize, } /// Results by parameter text, at most `max_entries` and `max_bytes` of them, the least recently /// used going first. pub(crate) struct SourceCache { map: HashMap>, clock: u64, bytes: usize, max_entries: usize, max_bytes: usize, } impl SourceCache { pub(crate) fn new(max_entries: usize, max_bytes: usize) -> Self { SourceCache { map: HashMap::new(), clock: 0, bytes: 0, max_entries, max_bytes } } fn remove(&mut self, src: &str) { if let Some(e) = self.map.remove(src) { self.bytes = self.bytes.saturating_sub(e.bytes); } } /// Forget the results read from `path`. fn forget_file(&mut self, path: &str) { let stale: Vec = self.map.iter().filter(|(_, e)| e.files.iter().any(|(p, _)| p == path)).map(|(k, _)| k.clone()).collect(); for src in stale { self.remove(&src); } } /// Keep within the bounds, always the result for `keep`. fn evict(&mut self, keep: &str) { while self.map.len() > self.max_entries || (self.bytes > self.max_bytes && self.map.len() > 1) { let Some(oldest) = self.map.iter().filter(|(k, _)| k.as_str() != keep).min_by_key(|(_, e)| e.used).map(|(k, _)| k.clone()) else { break }; self.remove(&oldest); } } /// The files the result cached for `src` was read from. pub(crate) fn files(&self, src: &str) -> Option> { self.map.get(src).map(|e| e.files.iter().map(|(p, _)| p.clone()).collect()) } #[cfg(test)] pub(crate) fn len(&self) -> usize { self.map.len() } #[cfg(test)] pub(crate) fn contains(&self, src: &str) -> bool { self.map.contains_key(src) } #[cfg(test)] pub(crate) fn bytes(&self) -> (usize, usize, usize) { (self.bytes, self.map.values().map(|e| e.bytes).sum(), self.max_bytes) } } /// Lock a cache; a panic elsewhere while it was held leaves a usable map. pub(crate) fn lock(cache: &Mutex>) -> MutexGuard<'_, SourceCache> { cache.lock().unwrap_or_else(PoisonError::into_inner) } /// A cache that registers with [`check_lut_files`] on first use. pub(crate) struct Registered { cache: OnceLock>>, max_entries: usize, max_bytes: usize, } impl Registered { pub(crate) const fn new(max_entries: usize, max_bytes: usize) -> Self { Registered { cache: OnceLock::new(), max_entries, max_bytes } } pub(crate) fn get(&'static self) -> &'static Mutex> { self.cache.get_or_init(|| { registry().push(self); Mutex::new(SourceCache::new(self.max_entries, self.max_bytes)) }) } } /// A cache [`check_lut_files`] tells to forget the results read from a changed file. trait ForgetFile: Sync { fn forget_file(&self, path: &str); /// Add the files the cached results were read from to `out`. fn held_files(&self, out: &mut HashSet); } impl ForgetFile for Registered { fn forget_file(&self, path: &str) { if let Some(c) = self.cache.get() { lock(c).forget_file(path); } } fn held_files(&self, out: &mut HashSet) { if let Some(c) = self.cache.get() { out.extend(lock(c).map.values().flat_map(|e| e.files.iter().map(|(p, _)| p.clone()))); } } } fn registry() -> MutexGuard<'static, Vec<&'static dyn ForgetFile>> { static REGISTRY: OnceLock>> = OnceLock::new(); REGISTRY.get_or_init(Mutex::default).lock().unwrap_or_else(PoisonError::into_inner) } thread_local! { /// The loads running on this thread, innermost last: the files each read, and the bytes of /// the cached results it holds (a config holds the LUTs its `FileTransform`s loaded). static READING: RefCell> = const { RefCell::new(Vec::new()) }; } /// Note that the running load read (or looked for) `path`, stamped `stamp`. pub(crate) fn note_file(path: &str, stamp: FileStamp) { READING.with(|r| { if let Ok(mut r) = r.try_borrow_mut() && let Some((top, _)) = r.last_mut() && !top.iter().any(|(p, _)| p == path) { top.push((path.to_string(), stamp)); } }); } /// Note that the running load holds a cached result of `bytes`. fn note_bytes(bytes: usize) { READING.with(|r| { if let Ok(mut r) = r.try_borrow_mut() && let Some((_, held)) = r.last_mut() { *held = held.saturating_add(bytes); } }); } /// Pops the files of a load when it ends, even by a panic. struct Reading { popped: bool, } impl Reading { fn start() -> Reading { READING.with(|r| { if let Ok(mut r) = r.try_borrow_mut() { r.push((Vec::new(), 0)); } }); Reading { popped: false } } fn pop() -> Option<(Files, usize)> { READING.with(|r| r.try_borrow_mut().ok().and_then(|mut r| r.pop())) } /// The files the load read, and the bytes of the cached results it holds. fn finish(mut self) -> (Files, usize) { self.popped = true; Self::pop().unwrap_or_default() } } impl Drop for Reading { fn drop(&mut self) { if !self.popped { let _ = Self::pop(); } } } /// The stamp of the file at `path` now: one `metadata` call. pub(crate) fn file_stamp(path: &str) -> FileStamp { std::fs::metadata(path).ok().map(|md| (md.len(), md.modified().ok())) } /// Read the text file at `path` for the running load, stamped before reading (a file written /// after it was stamped has a newer stamp, and is read again next time). pub(crate) fn read(path: &str) -> std::io::Result { note_file(path, file_stamp(path)); std::fs::read_to_string(path) } /// Note that the running load looked for `path` and did not find it: it loads again once the file /// appears. pub(crate) fn note_missing(path: &str) { note_file(path, None); } /// The result cached for `src`, or `load`'s (and its size estimate in bytes), cached. `load` reads /// files with [`read`] (and notes the ones it looked for with [`note_missing`]); no lock is held /// while it runs or while the files are stamped. pub(crate) fn cached(cache: &Mutex>, src: &str, load: impl FnOnce() -> (V, usize)) -> V { let files = lock(cache).map.get(src).map(|e| e.files.clone()); let stale = files.is_some(); if let Some(files) = files && files.iter().all(|(p, s)| file_stamp(p) == *s) { let mut c = lock(cache); c.clock += 1; let now = c.clock; if let Some(e) = c.map.get_mut(src) && e.files == files { e.used = now; let (value, bytes) = (e.value.clone(), e.bytes); drop(c); // (an enclosing load depends on these files too, and holds this result) for (p, s) in &files { note_file(p, *s); } note_bytes(bytes); return value; } } let reading = Reading::start(); let (value, size) = load(); let (files, held) = reading.finish(); follow(&files, stale); for (p, s) in &files { note_file(p, *s); } // (what it holds counts against this cache's bound too: another cache letting go of it // frees nothing while this result keeps it) let bytes = size.saturating_add(held).saturating_add(src.len()); note_bytes(bytes); let mut c = lock(cache); c.clock += 1; let used = c.clock; c.remove(src); c.map.insert(src.to_string(), Entry { files, value: value.clone(), used, bytes }); c.bytes = c.bytes.saturating_add(bytes); c.evict(src); value } /// How often a file a cached load read was found changed on disk ([`lut_generation`]). static GENERATION: AtomicU64 = AtomicU64::new(0); /// The files followed by [`check_lut_files`]: the stamp each was last read with, and when. #[derive(Default)] struct Followed { files: HashMap, clock: u64, } fn followed() -> MutexGuard<'static, Followed> { static FOLLOWED: OnceLock> = OnceLock::new(); FOLLOWED.get_or_init(Mutex::default).lock().unwrap_or_else(PoisonError::into_inner) } impl Followed { /// Note that `files` were read with these stamps; true when one has a different stamp than /// its last read's: a file changed on disk. fn read(&mut self, files: &Files) -> bool { let mut moved = false; for (path, stamp) in files { self.clock += 1; let now = self.clock; if self.files.insert(path.clone(), (*stamp, now)).is_some_and(|(old, _)| old != *stamp) { moved = true; } } moved } /// Keep at most [`MAX_FOLLOWED_FILES`], letting go of the least recently read first but never /// of a file in `held` (a cached result was read from it) or in `files` (just read). fn trim(&mut self, held: &HashSet, files: &Files) { while self.files.len() > MAX_FOLLOWED_FILES { let Some(oldest) = self .files .iter() .filter(|(p, _)| !held.contains(p.as_str()) && !files.iter().any(|(f, _)| f == *p)) .min_by_key(|(_, (_, used))| *used) .map(|(p, _)| p.clone()) else { break; }; self.files.remove(&oldest); } } } /// The files the registered caches' results were read from. fn held_files() -> HashSet { let caches: Vec<&'static dyn ForgetFile> = registry().clone(); let mut out = HashSet::new(); for c in caches { c.held_files(&mut out); } out } /// Note that `files` were read with these stamps. A file read with a different stamp than last /// time, or a load replacing a result whose files moved (`stale`), means a file changed on disk, /// and frames made before may show the old contents. fn follow(files: &Files, stale: bool) { let (moved, over) = { let mut f = followed(); (f.read(files), f.files.len() > MAX_FOLLOWED_FILES) }; if over { // (gathered without the followed files' lock: no two of these locks are ever nested) let held = held_files(); followed().trim(&held, files); } if moved || stale { GENERATION.fetch_add(1, Ordering::AcqRel); } } /// Changes each time a file a cached load read is found changed on disk (by a load itself or /// [`check_lut_files`]): frames made before then may show the old contents. pub fn lut_generation() -> u64 { GENERATION.load(Ordering::Acquire) } /// Look at every file read (one `metadata` call each) and forget the results read from the ones /// that changed on disk since, so the next load reads them again. Returns [`lut_generation`]. pub fn check_lut_files() -> u64 { let files: Vec<(String, FileStamp)> = followed().files.iter().map(|(p, (s, _))| (p.clone(), *s)).collect(); // (stamped without the lock: a file on a slow share must not hold up renders) let changed: Vec<(String, FileStamp, FileStamp)> = files.into_iter().filter_map(|(path, old)| Some(file_stamp(&path)).filter(|now| *now != old).map(|now| (path, old, now))).collect(); let caches: Vec<&'static dyn ForgetFile> = registry().clone(); for (path, old, now) in changed { { let mut f = followed(); // (a render that read the file meanwhile has noted its new stamp already) match f.files.get_mut(&path) { Some((s, _)) if *s == old => *s = now, _ => continue, } } for c in &caches { c.forget_file(&path); } GENERATION.fetch_add(1, Ordering::AcqRel); } lut_generation() } #[cfg(test)] pub(crate) fn followed_stamp(path: &str) -> Option { followed().files.get(path).map(|(s, _)| *s) } #[cfg(test)] mod tests { use super::*; /// Past [`MAX_FOLLOWED_FILES`], the file just read is still followed (a list of its own: the /// shared one's files belong to the other tests too). #[test] fn the_file_just_read_stays_followed_past_the_limit() { let mut f = Followed::default(); let held: HashSet = ["/followed/0.cube".to_string()].into(); for i in 0..MAX_FOLLOWED_FILES + 8 { let files = vec![(format!("/followed/{i}.cube"), Some((1, None)))]; assert!(!f.read(&files)); f.trim(&held, &files); assert!(f.files.contains_key(&files[0].0), "{i}: the file just read"); assert!(f.files.len() <= MAX_FOLLOWED_FILES); } assert!(f.files.contains_key("/followed/0.cube"), "a file a cached result was read from"); assert!(!f.files.contains_key("/followed/1.cube"), "the least recently read other"); assert!(f.read(&vec![("/followed/1030.cube".into(), Some((2, None)))]), "a moved stamp"); } /// A nested cached load's files count for the enclosing load. #[test] fn an_enclosing_load_depends_on_a_nested_loads_files() { static INNER: Registered = Registered::new(8, 1 << 20); static OUTER: Registered = Registered::new(8, 1 << 20); let v = cached(OUTER.get(), "outer", || { note_missing("/nested/outer-own.cube"); let inner = cached(INNER.get(), "inner", || { note_missing("/nested/inner.cube"); (7, 100) }); (inner, 0) }); assert_eq!(v, 7); let files = lock(OUTER.get()).files("outer").unwrap(); let held = |src: &str| lock(OUTER.get()).map.get(src).map(|e| e.bytes); // ("inner" is 5 bytes, its result 100: "outer" holds it, on a load and on a hit alike) assert_eq!(held("outer"), Some(100 + 5 + "outer".len()), "the result an enclosing load holds counts"); assert_eq!(files, vec!["/nested/outer-own.cube".to_string(), "/nested/inner.cube".to_string()]); // A hit on the inner result still reports its files to a new enclosing load. let w = cached(OUTER.get(), "outer 2", || (cached(INNER.get(), "inner", || (0, 0)), 0)); assert_eq!(w, 7); assert_eq!(lock(OUTER.get()).files("outer 2").unwrap(), vec!["/nested/inner.cube".to_string()]); assert_eq!(held("outer 2"), Some(100 + 5 + "outer 2".len())); } }