From 61382118047db2dacfc7a238e9a6fc88b64d7594 Mon Sep 17 00:00:00 2001 From: vangel76 Date: Mon, 9 Nov 2026 01:16:30 +0100 Subject: [PATCH] #3298: cache policy: slow value decay, the process's measured memory, a bounded preview overage, disk writes that pay off, capped open files - Value decays by ln(seconds unused + 1) + 1 instead of halving every 30 s. - Each balance reads the process's resident memory (memory-stats, at most every 250 ms): over 95 % of the RAM left after the reserve the caches give way by what it is over; what they freed for it counts as freed; over all of it also protected preview frames go. - Frames a playing preview shows next go last and may keep the caches over the budget by a tenth of it (at most 1 GB). - Frames and plane sets go to the disk cache only when making them again costs more than reading them back (measured read rate, 10 ms per MB until measured). - At most 256 movie/audio files stay open (least recently used idle one closed). --- Cargo.lock | 11 + Cargo.toml | 2 + crates/engine/Cargo.toml | 1 + crates/engine/src/settings/prefs.rs | 4 +- crates/engine/src/settings/prefs/queries.rs | 17 ++ .../engine/src/settings/session_settings.rs | 10 + crates/engine/src/system/sysinfo.rs | 14 ++ crates/media/src/exr_planes.rs | 12 +- crates/media/src/exr_planes/tests.rs | 2 + crates/media/src/pool.rs | 67 ++++- crates/render/src/cache.rs | 2 +- crates/render/src/disk_cache.rs | 72 +++++- crates/render/src/memory.rs | 234 ++++++++++++++++-- crates/ui-egui/src/frames.rs | 25 +- crates/ui-egui/src/frames/tests.rs | 32 +-- docs/preferences.md | 28 ++- 16 files changed, 471 insertions(+), 62 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index ba347f1a7..4f047a9a1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1554,6 +1554,7 @@ dependencies = [ "image", "kurbo", "log", + "memory-stats", "rayon", "same-file", "serde", @@ -3948,6 +3949,16 @@ dependencies = [ "autocfg", ] +[[package]] +name = "memory-stats" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c73f5c649995a115e1a0220b35e4df0a1294500477f97a91d0660fb5abeb574a" +dependencies = [ + "libc", + "windows-sys 0.52.0", +] + [[package]] name = "minicov" version = "0.3.8" diff --git a/Cargo.toml b/Cargo.toml index abb2256c2..302a05a84 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -59,6 +59,8 @@ thiserror = "2" serde = { version = "1", features = ["derive", "rc"] } serde_json = { version = "1", features = ["float_roundtrip"] } log = "0.4" +# The process's own memory use for the memory accountant (#3301; MIT OR Apache-2.0). +memory-stats = "1.2" # All date/time conversion goes through chrono (no hand-rolled calendar code beyond the 400-year range extension; AGENTS.md). chrono = { version = "0.4.45", default-features = false, features = ["std"] } rayon = "1" diff --git a/crates/engine/Cargo.toml b/crates/engine/Cargo.toml index aa5956ebe..cd85c858d 100644 --- a/crates/engine/Cargo.toml +++ b/crates/engine/Cargo.toml @@ -43,6 +43,7 @@ exr = { workspace = true } # Native file identity and SAM 2 inference; browsers keep the built-in engines. [target.'cfg(not(target_arch = "wasm32"))'.dependencies] +memory-stats = { workspace = true } same-file = { workspace = true } tempfile = { workspace = true } effectcraft-sam2 = { workspace = true } diff --git a/crates/engine/src/settings/prefs.rs b/crates/engine/src/settings/prefs.rs index 4743f5292..1f855f8ed 100644 --- a/crates/engine/src/settings/prefs.rs +++ b/crates/engine/src/settings/prefs.rs @@ -28,8 +28,8 @@ pub use choices::{APPEARANCE_MODES, DARK_THEMES, LANGUAGES, LIGHT_THEMES, THEMES pub use dialog::{Item, Kind, Page, pages, pages_json, todo_keys}; pub use document::{migrate, page_id, section_key}; pub use queries::{ - CacheCaps, FALLBACK_MEMORY_BUDGET, MEMORY_HEADROOM_PERCENT, MIN_MEMORY_BUDGET, MemoryBudget, WEB_LAYER_CACHE, WEB_MEDIA_CACHE, WEB_MEMORY_BUDGET, - WEB_PREVIEW_CACHE, mask_color, + CacheCaps, FALLBACK_MEMORY_BUDGET, MEMORY_HEADROOM_PERCENT, MIN_MEMORY_BUDGET, MemoryBudget, PROCESS_PURGE_PERCENT, WEB_LAYER_CACHE, WEB_MEDIA_CACHE, + WEB_MEMORY_BUDGET, WEB_PREVIEW_CACHE, mask_color, }; pub use recent::{MAX_RECENT_SCRIPTS, RecentScript}; pub use sections::{ diff --git a/crates/engine/src/settings/prefs/queries.rs b/crates/engine/src/settings/prefs/queries.rs index e48518906..c15d48269 100644 --- a/crates/engine/src/settings/prefs/queries.rs +++ b/crates/engine/src/settings/prefs/queries.rs @@ -29,6 +29,17 @@ impl Prefs { } } + /// The limits on the process's measured memory (bytes): above the first the caches give way + /// by what it is over, above the second also the frames a playing preview shows next + /// ([`PROCESS_PURGE_PERCENT`] of the installed RAM left after the reserve, and all of it). + /// `None` while the installed RAM is unknown. + pub fn process_limits(&self, mem: Option) -> Option<(u64, u64)> { + let total = mem.map(|m| m.total).filter(|t| *t > 0)?; + let room = total.saturating_sub(u64::from(self.memory.ram_reserved_gb) << 30).max(MIN_MEMORY_BUDGET); + let purge = u64::try_from(u128::from(room) * u128::from(PROCESS_PURGE_PERCENT) / 100).unwrap_or(room); + Some((purge, room)) + } + /// The memory EffectCraft's caches share (Settings ▸ Memory & CPU): the layer cache, the /// footage frames, the decoded OpenEXR planes and the RAM preview frames together, kept within /// it by the memory accountant (`effectcraft_render::memory::Accountant`), which decides @@ -161,6 +172,12 @@ pub const WEB_LAYER_CACHE: u64 = 512 << 20; /// The most the footage frame cache holds in the browser (see [`WEB_LAYER_CACHE`]). pub const WEB_MEDIA_CACHE: u64 = 256 << 20; +/// Above this part (percent) of the installed RAM left after **RAM Reserved for Other +/// Applications**, the process's measured memory makes the caches give way even within their +/// budget ([`Prefs::process_limits`]): above the caches' budget plus most of the room left for +/// the app's own working memory. +pub const PROCESS_PURGE_PERCENT: u64 = 95; + /// The part (percent) of the installed RAM left after **RAM Reserved for Other Applications** /// that EffectCraft's caches share ([`Prefs::memory_budget`]). The rest is headroom for /// EffectCraft's own working memory (decoders, render buffers, undo, GPU staging, the interface), diff --git a/crates/engine/src/settings/session_settings.rs b/crates/engine/src/settings/session_settings.rs index bf4acbde3..cc25f35ea 100644 --- a/crates/engine/src/settings/session_settings.rs +++ b/crates/engine/src/settings/session_settings.rs @@ -122,6 +122,13 @@ impl Session { let layers: std::sync::Arc = self.layer_cache.clone(); accountant.register(&layers); accountant.set_budget(b.bytes); + // The process's measured memory as well (#3301: memory nobody accounts for, such as GPU + // staging, effect buffers and the allocator's fragmentation): over the purge limit the + // caches give way by what it is over, over the hard limit also the frames a playing + // preview shows next. + if let Some((purge_at, hard_at)) = self.prefs.process_limits(self.sys_memory) { + accountant.set_process_memory(crate::sysinfo::process_memory, purge_at, hard_at); + } } /// The memory the caches share for the last memory reading ([`Prefs::memory_budget`]), kept @@ -150,6 +157,9 @@ impl Session { self.sys_memory = reading.or(self.sys_memory); self.memory_low = self.sys_memory.is_some_and(|m| m.still_low(self.memory_low)); let after = self.memory_budget(); + // (the process's memory is checked with each balance; a reading now and then also + // when the caches don't grow) + effectcraft_render::memory::Accountant::global().balance(); if after != before { self.apply_cache_budgets(); // Frontends re-apply their preview cache budget. diff --git a/crates/engine/src/system/sysinfo.rs b/crates/engine/src/system/sysinfo.rs index b86fbbce0..8c594b214 100644 --- a/crates/engine/src/system/sysinfo.rs +++ b/crates/engine/src/system/sysinfo.rs @@ -152,6 +152,20 @@ pub fn parse_freebsd_sysctl(text: &str) -> Option { Some(SysMemory { total, available: free.saturating_mul(page).min(total) }) } +/// The physical memory this process uses now (its resident set, the working set on Windows), in +/// bytes; `None` where it can't be read (the browser). Cheap: the memory accountant reads it +/// with each balance (at most every 250 ms). +pub fn process_memory() -> Option { + #[cfg(not(target_arch = "wasm32"))] + { + memory_stats::memory_stats().and_then(|m| u64::try_from(m.physical_mem).ok()) + } + #[cfg(target_arch = "wasm32")] + { + None + } +} + /// Total and available physical memory, when the system reports them. pub fn memory() -> Option { #[cfg(target_os = "linux")] diff --git a/crates/media/src/exr_planes.rs b/crates/media/src/exr_planes.rs index e3607b15d..584a5d14c 100644 --- a/crates/media/src/exr_planes.rs +++ b/crates/media/src/exr_planes.rs @@ -724,7 +724,7 @@ impl PlaneStore { let e = st.entries.get(Self::oldest_droppable(&st, None, false)?)?; let cost_us = if e.cost_us > 0 { e.cost_us } else { effectcraft_render::memory::default_cost(e.bytes, effectcraft_render::memory::DEFAULT_PLANE_US_PER_MB) }; - Some(effectcraft_render::memory::Candidate { used: e.used, bytes: e.bytes, cost_us }) + Some(effectcraft_render::memory::Candidate { used: e.used, bytes: e.bytes, cost_us, protected: false }) } /// Drop [`PlaneStore::oldest_candidate`]; the bytes freed. @@ -958,12 +958,15 @@ fn decode(path: &str, source: &ExrSource, flight: &Arc, base: Option = missing.iter().zip(&kept).filter(|(_, k)| k.is_none()).map(|(id, _)| *id).collect(); let from_disk = to_read.is_empty(); + // (what reading the planes took: their cost, against reading them back from the disk cache) + let read_from = effectcraft_render::memory::tick(); let (read, stats) = if to_read.is_empty() { (Ok(vec![]), Default::default()) } else { let request = ReadRequest { max_bytes: cap_of(path), ..ReadRequest::full(to_read.clone()) }; read_planes(&mut *opened.reader, &index, &request) }; + let read_took = effectcraft_render::memory::tick().saturating_sub(read_from); #[cfg(test)] DECODES.lock().unwrap_or_else(PoisonError::into_inner).push((path.to_string(), DecodeRecord { channels: names.clone(), stats: stats.clone(), from_disk })); #[cfg(not(test))] @@ -1023,7 +1026,12 @@ fn decode(path: &str, source: &ExrSource, flight: &Arc, base: Option())).fold(0, usize::saturating_add); + let took_us = read_took; + if d.pays_off(bytes, took_us) { + d.put_planes(w as u32, h as u32, planes, &entry, since); + } } } Ok(batch) diff --git a/crates/media/src/exr_planes/tests.rs b/crates/media/src/exr_planes/tests.rs index 978581d45..a146fdb4b 100644 --- a/crates/media/src/exr_planes/tests.rs +++ b/crates/media/src/exr_planes/tests.rs @@ -957,6 +957,8 @@ fn decoded_planes_are_kept_on_disk_and_read_back_exactly() { let file = dir.join("crypto_0001.exr"); std::fs::write(&file, multipart()).unwrap(); let dc = DiskCache::open(dir.join("cache"), 1 << 30).unwrap(); + // (every decode is written, however quick: not decided by this machine's speed) + dc.set_read_us_per_mb(0); // (only this test's files use it) use_disk_for(&dir.to_string_lossy()); set_disk_cache(Some(&dc)); diff --git a/crates/media/src/pool.rs b/crates/media/src/pool.rs index 6da73ec80..3dd5e0334 100644 --- a/crates/media/src/pool.rs +++ b/crates/media/src/pool.rs @@ -412,6 +412,40 @@ enum Waited { No, } +/// At most this many movie/audio files are kept open ([`Sources`]): the least recently used one +/// nobody is using is closed beyond it (it opens again when asked for; a project that cycles +/// through more files than this opens them again each time). +/// Still images and image sequences keep no file open (an OpenEXR file is opened for one decode). +const MAX_OPEN_SOURCES: usize = 256; + +/// The opened movie/audio sources by path, with when each was last asked for. +#[derive(Default)] +struct Sources { + map: HashMap, (SourceSlot, u64)>, + clock: u64, +} + +impl Sources { + /// The slot of `path` (new when there is none), as just used; the least recently used slot + /// beyond [`MAX_OPEN_SOURCES`] is dropped. + fn slot(&mut self, path: &Arc) -> SourceSlot { + self.clock = self.clock.wrapping_add(1); + let clock = self.clock; + let slot = { + let e = self.map.entry(path.clone()).or_insert_with(|| (SourceSlot::default(), clock)); + e.1 = clock; + e.0.clone() + }; + // (only a slot nobody is using or opening: an open in progress isn't started twice) + if self.map.len() > MAX_OPEN_SOURCES + && let Some(oldest) = self.map.iter().filter(|(_, (s, _))| Arc::strong_count(s) == 1).min_by_key(|(_, (_, used))| *used).map(|(p, _)| p.clone()) + { + self.map.remove(&oldest); + } + slot + } +} + /// A movie/audio source by path ([`Opened`]), opened by the first caller while the others wait /// for it (`None`: failed to open; not retried until `forget`), with the file's identity as /// opened. @@ -448,8 +482,8 @@ fn channel_order(src: &SharedSource, header: Option<&[u8]>, file: Option<&dyn fi type GifSlot = Arc, String>, ReadFile)>>; struct Inner { - /// Opened movie/audio sources by path. - sources: Mutex, SourceSlot>>, + /// Opened movie/audio sources by path, at most [`MAX_OPEN_SOURCES`]. + sources: Mutex, /// Files opened into `sources` (see [`PoolStats::opened`]). opened: AtomicU64, /// In-memory files registered with `add_bytes` (web builds, tests). @@ -717,13 +751,13 @@ impl MediaPool { /// Drop every cached frame and decoder. pub fn clear(&self) { self.clear_frames(); - lock(&self.inner.sources).clear(); + lock(&self.inner.sources).map.clear(); lock(&self.inner.problems).clear(); } /// Forget a file (after it changed on disk, or to retry a file that failed to open). pub fn forget(&self, path: &str) { - lock(&self.inner.sources).remove(path); + lock(&self.inner.sources).map.remove(path); lock(&self.inner.models).remove(path); lock(&self.inner.gifs).remove(path); lock(&self.inner.problems).remove(path); @@ -1027,7 +1061,7 @@ impl Inner { /// each decoded a long FLAC in full at once (#408). /// Each call notes the file as read (see [`crate::reads`]), with its identity as opened. fn opened(&self, path: &Arc) -> Option { - let slot = lock(&self.sources).entry(path.clone()).or_default().clone(); + let slot = lock(&self.sources).slot(path); let (opened, file) = slot.get_or_init(|| self.open(path)); reads::note(file.clone()); opened.clone() @@ -1578,8 +1612,9 @@ impl effectcraft_render::memory::MemoryHolder for Inner { fn oldest(&self) -> Option { use effectcraft_render::memory::Candidate; let c = lock(&self.cache); - let frame = c.lru.oldest().and_then(|(k, _)| c.lru.map.get(k)).map(|e| Candidate { used: e.used, bytes: e.bytes, cost_us: e.cost_us }); - let still = c.recent.front().map(|r| Candidate { used: r.used, bytes: r.bytes.max(1), cost_us: 0 }); + let frame = + c.lru.oldest().and_then(|(k, _)| c.lru.map.get(k)).map(|e| Candidate { used: e.used, bytes: e.bytes, cost_us: e.cost_us, protected: false }); + let still = c.recent.front().map(|r| Candidate { used: r.used, bytes: r.bytes.max(1), cost_us: 0, protected: false }); match (frame, still) { (Some(f), Some(s)) => Some(if s.used < f.used { s } else { f }), (f, s) => f.or(s), @@ -2427,4 +2462,22 @@ mod tests { assert!(c.stale("/b.exr", at), "older than the remembered paths: stale"); assert!(!c.stale("/b.exr", c.generation)); } + + /// #3301: open movie/audio files are capped: beyond [`MAX_OPEN_SOURCES`] the least recently + /// asked for is closed (a project of thousands of clips kept every one open). + #[test] + fn open_sources_are_capped_least_recently_used_first() { + let mut s = Sources::default(); + let path = |i: usize| -> Arc { format!("/clips/{i}.mov").into() }; + let first = s.slot(&path(0)); + for i in 1..MAX_OPEN_SOURCES + 40 { + s.slot(&path(i)); + // (the first clip is asked for again and again: it stays) + s.slot(&path(0)); + } + assert_eq!(s.map.len(), MAX_OPEN_SOURCES); + assert!(s.map.contains_key(&path(0)), "used lately: kept"); + assert!(!s.map.contains_key(&path(1)), "the least recently used went"); + assert!(Arc::ptr_eq(&first, &s.slot(&path(0))), "a kept slot is the same slot"); + } } diff --git a/crates/render/src/cache.rs b/crates/render/src/cache.rs index 2248326ed..1fcb62e1d 100644 --- a/crates/render/src/cache.rs +++ b/crates/render/src/cache.rs @@ -1046,7 +1046,7 @@ impl crate::memory::MemoryHolder for LayerCache { fn oldest(&self) -> Option { let g = self.inner.lock().ok()?; let e = g.map.get(&g.oldest_key()?)?; - Some(crate::memory::Candidate { used: e.used, bytes: e.bytes, cost_us: e.cost_us }) + Some(crate::memory::Candidate { used: e.used, bytes: e.bytes, cost_us: e.cost_us, protected: false }) } fn drop_oldest(&self) -> usize { let Ok(mut g) = self.inner.lock() else { return 0 }; diff --git a/crates/render/src/disk_cache.rs b/crates/render/src/disk_cache.rs index 4c7817280..097ab53e3 100644 --- a/crates/render/src/disk_cache.rs +++ b/crates/render/src/disk_cache.rs @@ -53,6 +53,11 @@ const MAGIC: &[u8; 4] = b"ECDC"; /// Pending layer and matte writes before new ones are dropped. #[cfg(not(target_arch = "wasm32"))] const QUEUE_LIMIT: usize = 64; +/// What reading a megabyte of a disk cache entry back is assumed to take until reads are +/// measured, in microseconds: 10 ms (100 MB/s, a slow disk or a network share), so a quick frame +/// is not written on a guess ([`DiskCache::pays_off`]). +pub const DEFAULT_READ_US_PER_MB: u64 = 10_000; + /// Pending frame bytes before new frames are dropped. Frames have their own lane, written /// before layer buffers: a burst of large layer writes used to fill the shared queue and drop /// frames, so a fully cached comp came back with gaps in its blue bar. @@ -524,6 +529,9 @@ pub struct DiskCache { queue: Arc<(Mutex, Condvar)>, /// Layer buffers that took less than this to render are not written (ms). min_layer_ms: AtomicU64, + /// What reading a megabyte of an entry takes, in microseconds ([`DiskCache::pays_off`]): + /// [`DEFAULT_READ_US_PER_MB`] until reads are measured, then their running average. + read_us_per_mb: AtomicU64, /// Files whose entries are being deleted ([`DiskCache::drop_files`]), each with the number /// of drops of it pending: until then an entry made of one is a miss. dropping: Mutex, u32>>, @@ -636,6 +644,7 @@ impl DiskCache { Condvar::new(), )), min_layer_ms: AtomicU64::new(30), + read_us_per_mb: AtomicU64::new(DEFAULT_READ_US_PER_MB), dropping: Mutex::new(HashMap::new()), #[cfg(test)] head_bytes: AtomicU64::new(0), @@ -771,6 +780,38 @@ impl DiskCache { self.min_layer_ms.load(Ordering::Relaxed) } + /// What reading `bytes` of an entry back is expected to take, in microseconds (the measured + /// read rate, [`DiskCache::note_read`]). + pub fn read_us(&self, bytes: usize) -> u64 { + let rate = u128::from(self.read_us_per_mb.load(Ordering::Relaxed)); + u64::try_from(u128::try_from(bytes).unwrap_or(u128::MAX).saturating_mul(rate) >> 20).unwrap_or(u64::MAX) + } + + /// Set the read rate assumed until reads are measured (microseconds per MB; tests that need + /// every write give 0: everything pays off). + pub fn set_read_us_per_mb(&self, us: u64) { + self.read_us_per_mb.store(us, Ordering::Relaxed); + } + + /// Whether a frame or plane set of `bytes` that took `make_us` microseconds to make is worth + /// a disk write: only when making it again costs more than reading it back (#3301). A RAM + /// eviction keeps the disk copy either way. + pub fn pays_off(&self, bytes: usize, make_us: u64) -> bool { + let read = self.read_us(bytes); + read == 0 || make_us > read + } + + /// Note a read of `bytes` that took `took_us` (reads of under 64 KB are too short to time): + /// the read rate becomes a running average (7/8 the old rate, 1/8 this read's). + fn note_read(&self, bytes: usize, took_us: u64) { + if bytes < 64 << 10 { + return; + } + let rate = u64::try_from(u128::from(took_us).saturating_mul(1 << 20) / u128::try_from(bytes).unwrap_or(1).max(1)).unwrap_or(u64::MAX); + let old = self.read_us_per_mb.load(Ordering::Relaxed); + self.read_us_per_mb.store(old.saturating_mul(7).saturating_add(rate) / 8, Ordering::Relaxed); + } + pub fn contains(&self, kind: Kind, key: u128) -> bool { self.index.lock().is_ok_and(|g| g.contains(kind, key)) } @@ -851,8 +892,12 @@ impl DiskCache { return None; } let path = self.path(kind, key); + let t0 = web_time::Instant::now(); let data = std::fs::read(&path).ok(); let ok = data.as_deref().and_then(|d| Some((*d.get(5)?, verify(d, kind)?.to_vec()))); + if let Some((_, payload)) = &ok { + self.note_read(payload.len(), u64::try_from(t0.elapsed().as_micros()).unwrap_or(u64::MAX)); + } if ok.is_none() { // Gone (another process evicted it) or damaged: forget it. if data.is_some() { @@ -1553,7 +1598,7 @@ impl crate::memory::MemoryHolder for DiskCache { fn oldest(&self) -> Option { let q = self.queue.0.lock().ok()?; let (_, bytes) = q.newest_unique()?; - Some(crate::memory::Candidate { used: 0, bytes, cost_us: 0 }) + Some(crate::memory::Candidate { used: 0, bytes, cost_us: 0, protected: false }) } fn drop_oldest(&self) -> usize { let Ok(mut q) = self.queue.0.lock() else { return 0 }; @@ -2940,4 +2985,29 @@ mod tests { assert!(!dc.made_of_dropped(&files, &dc.drops_now()), "read after the drop: used"); let _ = std::fs::remove_dir_all(&dir); } + + /// #3301: a frame or plane set is written only when making it again costs more than + /// reading it back: a cheap one is not written, an expensive one is; the read rate follows + /// the reads measured. + #[test] + fn only_items_dearer_to_make_than_to_read_are_written() { + let dir = tmpdir("pays-off"); + let dc = DiskCache::open(&dir, 1 << 30).unwrap(); + let eight_mb = 8 << 20; + // Until a read is measured: 10 ms per MB, 80 ms for 8 MB. + assert_eq!(dc.read_us(eight_mb), 8 * DEFAULT_READ_US_PER_MB); + assert!(!dc.pays_off(eight_mb, 1_000), "rendered in 1 ms: not written"); + assert!(dc.pays_off(eight_mb, 200_000), "rendered in 200 ms: written"); + // Reads measured at 1 ms per MB: a 20 ms frame of 8 MB is now worth writing. + assert!(!dc.pays_off(eight_mb, 20_000)); + for _ in 0..40 { + dc.note_read(1 << 20, 1_000); + } + assert!(dc.pays_off(eight_mb, 20_000), "{}", dc.read_us(eight_mb)); + // Tiny reads are not timed. + dc.note_read(100, 1_000_000); + assert!(dc.pays_off(eight_mb, 20_000)); + drop(dc); + let _ = std::fs::remove_dir_all(&dir); + } } diff --git a/crates/render/src/memory.rs b/crates/render/src/memory.rs index d7ab946e1..7859be071 100644 --- a/crates/render/src/memory.rs +++ b/crates/render/src/memory.rs @@ -8,7 +8,8 @@ //! //! An item's value is what it would cost to make again per byte ([`Candidate::cost_us`], the //! measured render or decode time where known, else a typical one: [`DEFAULT_LAYER_US_PER_MB`] -//! and its neighbours), decayed by the time since it was last used ([`HALF_LIFE_US`]): +//! and its neighbours), decayed slowly by the time since it was last used (by the logarithm of +//! the seconds unused, so a costly frame unused for minutes still outlives a cheap one): //! [`value`]. A copy of data another cache holds (a queued disk write) costs nothing to make //! again. Each holder offers the item it would drop next (its least recently used one, //! [`MemoryHolder::oldest`]); the accountant drops the least valuable of those, asks that holder @@ -28,10 +29,6 @@ use std::sync::{Arc, Mutex, MutexGuard, PoisonError, TryLockError, Weak}; /// The share of the budget the accountant frees down to once it is over (hysteresis). pub const TRIM_TO: f64 = 0.9; -/// An item unused this long is worth half as much as one just used ([`value`]), a quarter at -/// three times this, and so on (`1 / (1 + age / HALF_LIFE_US)`). -pub const HALF_LIFE_US: u64 = 30_000_000; - /// While a holder thrashes, its items are worth this many times more ([`value`]). pub const THRASH_BOOST: f64 = 4.0; @@ -79,7 +76,7 @@ const GROWTH_PART: usize = 16; const THRASH_FOR: std::time::Duration = std::time::Duration::from_secs(10); /// The item a holder would drop next ([`MemoryHolder::oldest`]). -#[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] pub struct Candidate { /// When it was last used ([`tick`]). pub used: u64, @@ -87,15 +84,53 @@ pub struct Candidate { pub bytes: usize, /// What making it again costs, in microseconds (0: a copy of data another cache holds). pub cost_us: u64, + /// About to be used: a frame a playing RAM preview shows next. Kept over the budget by up to + /// [`preview_overage`] while other items can go instead, never past the hard limit. + pub protected: bool, } -/// What an item is worth keeping at `now` ([`tick`]): its cost to make again per byte, halved -/// after [`HALF_LIFE_US`] unused, [`THRASH_BOOST`] times more while its holder thrashes. +impl Candidate { + /// An item that is not [`Candidate::protected`]. + pub fn new(used: u64, bytes: usize, cost_us: u64) -> Candidate { + Candidate { used, bytes, cost_us, protected: false } + } +} + +/// How far protected items (frames a playing preview shows next) may keep the caches over a +/// budget of `budget` bytes while other items can go instead: a tenth of it, at most 1 GB. +pub fn preview_overage(budget: usize) -> usize { + (budget / 10).min(1 << 30) +} + +/// How often the process's memory is read at most ([`Accountant::set_process_memory`]), in +/// [`tick`]'s units (microseconds). +const PROCESS_READ_EVERY: u64 = 250_000; + +/// The process's memory as the accountant watches it ([`Accountant::set_process_memory`]). +struct ProcessWatch { + /// Reads the memory the process uses now, in bytes (`None`: unknown). + read: Option Option>, + /// Above this the caches are trimmed by what is over, even when they are within their + /// budget (memory nobody accounts for: GPU staging, effect buffers, the allocator's + /// fragmentation)… + purge_at: u64, + /// …and above this also the protected items go ([`Candidate::protected`]). + hard_at: u64, + /// When it was last read ([`tick`]'s units). + read_at: Option, + /// What the caches freed for it since it was last under its purge limit: freed memory often + /// stays in the reading (the allocator keeps it), so it counts as freed; the caches give way + /// again only for memory that grew beyond that, and are never emptied for one reading. + credited: u64, +} + +/// What an item is worth keeping at `now` ([`tick`]): its cost to make again per byte, divided +/// by `ln(seconds unused + 1) + 1` (a slow decay: about a fifth after a minute unused, a +/// seventh after ten), [`THRASH_BOOST`] times more while its holder thrashes. pub fn value(c: &Candidate, now: u64, thrashing: bool) -> f64 { let per_byte = c.cost_us as f64 / c.bytes.max(1) as f64; - let age = now.saturating_sub(c.used) as f64; - let half = HALF_LIFE_US as f64; - let v = per_byte * half / (half + age); + let age_s = now.saturating_sub(c.used) as f64 / 1e6; + let v = per_byte / ((age_s + 1.0).ln() + 1.0); if thrashing { v * THRASH_BOOST } else { v } } @@ -140,6 +175,8 @@ pub struct Accountant { requested: AtomicBool, /// The clock items' ages are measured with ([`tick`]; tests give their own). clock: fn() -> u64, + /// The process's memory, read and checked by each balance. + process: Mutex, } impl Default for Accountant { @@ -164,9 +201,50 @@ impl Accountant { balancing: Mutex::new(None), requested: AtomicBool::new(false), clock, + process: Mutex::new(ProcessWatch { read: None, purge_at: u64::MAX, hard_at: u64::MAX, read_at: None, credited: 0 }), } } + /// Watch the process's memory with `read` (the bytes it uses now): a balance (at most every + /// 250 ms) trims the caches by what it is over `purge_at`, even while they are within their + /// budget, and above `hard_at` also the frames a playing preview shows next. + pub fn set_process_memory(&self, read: fn() -> Option, purge_at: u64, hard_at: u64) { + { + let mut p = self.process.lock().unwrap_or_else(PoisonError::into_inner); + p.read = Some(read); + p.purge_at = purge_at; + p.hard_at = hard_at.max(purge_at); + } + self.balance(); + } + + /// What a balance at `now` must free beyond the budget for the process's memory, and whether + /// it is past the hard limit (a reading at most every [`PROCESS_READ_EVERY`]). What the caches + /// already freed for it counts as freed ([`ProcessWatch::credited`]). + fn process_excess(&self, now: u64) -> (u64, bool) { + let mut p = self.process.lock().unwrap_or_else(PoisonError::into_inner); + let Some(read) = p.read else { return (0, false) }; + if p.read_at.is_some_and(|at| now.saturating_sub(at) < PROCESS_READ_EVERY) { + return (0, false); + } + p.read_at = Some(now); + let Some(used) = read() else { return (0, false) }; + if used <= p.purge_at { + p.credited = 0; + return (0, false); + } + let used = used.saturating_sub(p.credited); + // (down to the trim line under the purge limit, as for the budget) + let line = (p.purge_at as f64 * TRIM_TO) as u64; + (used.saturating_sub(line), used > p.hard_at) + } + + /// The caches freed `bytes` for the process's memory. + fn credit(&self, bytes: usize) { + let mut p = self.process.lock().unwrap_or_else(PoisonError::into_inner); + p.credited = p.credited.saturating_add(u64::try_from(bytes).unwrap_or(u64::MAX)); + } + /// The process's accountant. pub fn global() -> &'static Accountant { static GLOBAL: Accountant = Accountant::new(usize::MAX); @@ -282,27 +360,44 @@ impl Accountant { } /// One pass of [`Accountant::balance`] with the budget in force now. + /// + /// Over the budget the caches are freed down to [`TRIM_TO`] of it; with the process's memory + /// over its purge limit ([`Accountant::set_process_memory`]) also by what that is over. + /// Protected items ([`Candidate::protected`]) go last, and only while the caches are more than + /// [`preview_overage`] over the target (or the process is past its hard limit). fn balance_once(&self) { let budget = self.budget(); if budget == usize::MAX { return; } self.grown.store(0, Ordering::Relaxed); + let now = (self.clock)(); + let (excess, hard) = self.process_excess(now); let holders = self.alive(); let mut total: usize = holders.iter().map(|(h, _)| h.bytes()).fold(0, usize::saturating_add); - if total <= budget { + let excess = usize::try_from(excess).unwrap_or(usize::MAX); + if total <= budget && excess == 0 { return; } - let target = (budget as f64 * TRIM_TO) as usize; - let now = (self.clock)(); + let held = total; + let trimmed = if total > budget { (budget as f64 * TRIM_TO) as usize } else { total }; + // (the caches can free at most what they hold) + let target = trimmed.min(total.saturating_sub(excess.min(total))); + let overage = if hard { 0 } else { preview_overage(budget) }; // Each holder's next item (`None`: it has nothing more it may drop). let mut next: Vec> = holders.iter().map(|(h, _)| h.oldest()).collect(); while total > target { + // (protected items only once nothing else can go, or past the overage) + let any_unprotected = next.iter().flatten().any(|c| !c.protected); + let protected_ok = !any_unprotected && total > target.saturating_add(overage); let pick = next .iter() .enumerate() .filter_map(|(i, c)| { let c = (*c)?; + if c.protected && !protected_ok { + return None; + } let thrashing = holders.get(i).is_some_and(|(_, t)| *t); Some((i, value(&c, now, thrashing), c.used)) }) @@ -316,6 +411,11 @@ impl Accountant { total = total.saturating_sub(freed); self.freed.fetch_add(freed, Ordering::Relaxed); } + if excess > 0 { + // (what went beyond the budget's own trim was freed for the process's memory) + let for_budget = held.saturating_sub(trimmed.max(target)); + self.credit(held.saturating_sub(total).saturating_sub(for_budget).min(excess)); + } } } @@ -332,7 +432,7 @@ mod tests { impl Fake { fn new(name: &'static str, items: &[(u64, usize, u64)]) -> Arc { - let items = items.iter().map(|&(used, bytes, cost_us)| Candidate { used, bytes, cost_us }).collect(); + let items = items.iter().map(|&(used, bytes, cost_us)| Candidate::new(used, bytes, cost_us)).collect(); Arc::new(Fake { name, items: Mutex::new(items), refills: Mutex::new(0) }) } fn held(&self) -> usize { @@ -342,7 +442,7 @@ mod tests { self.items.lock().unwrap().len() } fn push(&self, used: u64, bytes: usize, cost_us: u64) { - self.items.lock().unwrap().push_back(Candidate { used, bytes, cost_us }); + self.items.lock().unwrap().push_back(Candidate::new(used, bytes, cost_us)); } } @@ -409,10 +509,16 @@ mod tests { /// one unused for long enough goes before a costlier one used just now. #[test] fn value_falls_with_time_unused() { - let c = |used, cost_us| Candidate { used, bytes: 100, cost_us }; + let c = |used, cost_us| Candidate::new(used, 100, cost_us); assert!(value(&c(0, 1000), at_100s(), false) < value(&c(99 * S, 1000), at_100s(), false)); - let half = value(&c(at_100s() - HALF_LIFE_US, 1000), at_100s(), false); - assert!((half - 5.0).abs() < 1e-9, "{half}"); + let fresh = value(&c(at_100s(), 1000), at_100s(), false); + assert!((fresh - 10.0).abs() < 1e-9, "{fresh}"); + let a_second = value(&c(at_100s() - S, 1000), at_100s(), false); + assert!((a_second - 10.0 / (2f64.ln() + 1.0)).abs() < 1e-9, "{a_second}"); + // #3301: the decay is slow: unused for ten minutes, an item keeps more than a tenth of its + // value (it kept under a twentieth when it halved every 30 s). + let ten_minutes = value(&c(0, 1000), 600 * S, false); + assert!(ten_minutes > fresh / 10.0, "{ten_minutes}"); assert!(value(&c(0, 2000), at_100s(), false) < value(&c(at_100s(), 1000), at_100s(), false)); assert_eq!(value(&c(at_100s(), 0), at_100s(), false), 0.0, "a copy is worth nothing"); assert_eq!(value(&c(0, 1000), at_100s(), true), THRASH_BOOST * value(&c(0, 1000), at_100s(), false)); @@ -635,4 +741,94 @@ mod tests { acc.note_growth(1); assert!(frames.held() <= 900, "{}", frames.held()); } + + static PROCESS_NOW: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + static PROCESS_CLOCK: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(100_000_000); + fn process_now() -> Option { + Some(PROCESS_NOW.load(Ordering::SeqCst)) + } + fn process_clock() -> u64 { + PROCESS_CLOCK.load(Ordering::SeqCst) + } + /// (the process-memory tests share the statics above: one at a time) + static PROCESS_SERIAL: Mutex<()> = Mutex::new(()); + + /// #3301: memory nobody accounts for (GPU staging, effect buffers, fragmentation): with the + /// caches within their budget but the process over its purge limit, the caches give way by + /// what it is over, least valuable first; a reading that stays high (freed memory not shown + /// yet) doesn't empty them; over the hard limit the protected items go too. + #[test] + fn the_process_memory_over_its_limit_trims_the_caches() { + let _serial = PROCESS_SERIAL.lock().unwrap_or_else(PoisonError::into_inner); + let frames = Fake::new("frames", &[]); + for i in 0..10 { + frames.push(i * S, 100, 1_000); + } + let acc = Accountant::with_clock(10_000, process_clock); + let held: Arc = frames.clone(); + acc.register(&held); + // Under its purge limit (2000): nothing goes. + PROCESS_NOW.store(1_500, Ordering::SeqCst); + acc.set_process_memory(process_now, 2_000, 3_000); + assert_eq!(frames.held(), 1000, "within the budget and the limit"); + // 2500 measured, down to the trim line under the limit (1800): 700 go. + PROCESS_CLOCK.fetch_add(PROCESS_READ_EVERY, Ordering::SeqCst); + PROCESS_NOW.store(2_500, Ordering::SeqCst); + acc.balance(); + assert_eq!(frames.held(), 300, "the caches gave way for the process"); + // The reading stays high (the memory not handed back yet), for a minute: what was freed + // counts, the caches are not drained. + for _ in 0..240 { + PROCESS_CLOCK.fetch_add(PROCESS_READ_EVERY, Ordering::SeqCst); + acc.balance(); + } + assert_eq!(frames.held(), 300, "the same reading doesn't drain the caches"); + // Read at most every 250 ms: a higher reading within that waits. + PROCESS_NOW.store(2_600, Ordering::SeqCst); + acc.balance(); + assert_eq!(frames.held(), 300); + // 100 more than last time: the caches give way by that. + PROCESS_CLOCK.fetch_add(PROCESS_READ_EVERY, Ordering::SeqCst); + acc.balance(); + assert_eq!(frames.held(), 200, "grown by 100: 100 more go"); + // Under the limit again, then over: counted afresh. + PROCESS_CLOCK.fetch_add(PROCESS_READ_EVERY, Ordering::SeqCst); + PROCESS_NOW.store(1_000, Ordering::SeqCst); + acc.balance(); + PROCESS_CLOCK.fetch_add(PROCESS_READ_EVERY, Ordering::SeqCst); + PROCESS_NOW.store(2_050, Ordering::SeqCst); + acc.balance(); + // (250 over the trim line, with nothing counted as freed: the 200 held go) + assert_eq!(frames.held(), 0, "counted afresh"); + } + + /// #3301: frames a playing preview shows next (protected) keep the caches over the budget by + /// at most a tenth of it while other items can go instead, and go once nothing else can or + /// past that overage; past the process's hard limit no overage is allowed. + #[test] + fn protected_items_go_last_and_only_a_bounded_way_over() { + let _serial = PROCESS_SERIAL.lock().unwrap_or_else(PoisonError::into_inner); + let preview = Fake::new("preview", &[]); + for i in 0..4 { + preview.items.lock().unwrap().push_back(Candidate { used: i * S, bytes: 100, cost_us: 1, protected: true }); + } + let footage = Fake::new("footage", &[(99 * S, 300, 1_000_000)]); + let acc = Accountant::with_clock(usize::MAX, process_clock); + let held: Vec> = vec![holder(&preview), holder(&footage)]; + for h in &held { + acc.register(h); + } + // 700 held, budget 500 (target 450, overage 50): the footage goes though worth more. + acc.set_budget(500); + assert_eq!((preview.held(), footage.held()), (400, 0)); + // Budget 300 (target 270, overage 30): nothing else left, the preview frames go down to + // the overage over the target. + acc.set_budget(300); + assert_eq!(preview.held(), 300, "over the target by at most the overage"); + // Past the process's hard limit: no overage. + PROCESS_CLOCK.fetch_add(PROCESS_READ_EVERY, Ordering::SeqCst); + PROCESS_NOW.store(10_000, Ordering::SeqCst); + acc.set_process_memory(process_now, 1_000, 2_000); + assert!(preview.held() <= 200, "{}", preview.held()); + } } diff --git a/crates/ui-egui/src/frames.rs b/crates/ui-egui/src/frames.rs index 0a633afa8..725385fff 100644 --- a/crates/ui-egui/src/frames.rs +++ b/crates/ui-egui/src/frames.rs @@ -378,19 +378,21 @@ impl effectcraft_engine::render::memory::MemoryHolder for PreviewMemory { self.0.lock().map(|c| c.bytes.saturating_sub(c.gpu_bytes)).unwrap_or(0) } // (only frames in RAM: dropping a GPU frame frees no RAM, and loses a viewer frame) - /// A frame a playing preview shows next counts as just used: it is about to be (#3298 - /// review: one rendered from cached layers costs little, and older footage outlived it, so - /// the preview played into live renders). A frame costs at least a typical render - /// ([`effectcraft_engine::render::memory::DEFAULT_PREVIEW_US_PER_MB`]): a quick one still stands for a whole comp. + /// A frame a playing preview shows next is protected: the accountant lets it keep the caches + /// over the budget by a bounded amount while other items can go instead (#3301: one rendered + /// from cached layers costs little, and older footage outlived it, so the preview played into + /// live renders). A frame costs at least a typical render + /// ([`effectcraft_engine::render::memory::DEFAULT_PREVIEW_US_PER_MB`]): a quick one still + /// stands for a whole comp. fn oldest(&self) -> Option { + use effectcraft_engine::render::memory::{Candidate, DEFAULT_PREVIEW_US_PER_MB, default_cost}; let c = self.0.lock().ok()?; let k = c.order.get(c.cpu_victim()?)?; let f = c.map.get(k)?; let bytes = f.img.bytes(); - let ahead = c.playhead.as_ref().is_some_and(|p| p.ahead(k).is_some()); - let used = if ahead { effectcraft_engine::render::memory::tick() } else { f.used }; - let cost_us = f.cost_us.max(effectcraft_engine::render::memory::default_cost(bytes, effectcraft_engine::render::memory::DEFAULT_PREVIEW_US_PER_MB)); - Some(effectcraft_engine::render::memory::Candidate { used, bytes, cost_us }) + let protected = c.playhead.as_ref().is_some_and(|p| p.ahead(k).is_some()); + let cost_us = f.cost_us.max(default_cost(bytes, DEFAULT_PREVIEW_US_PER_MB)); + Some(Candidate { used: f.used, bytes, cost_us, protected }) } fn drop_oldest(&self) -> usize { let Ok(mut c) = self.0.lock() else { return 0 }; @@ -1171,6 +1173,10 @@ impl Frames { // (only with the generation its render started at, for this cache: a frame // made of a file Reload Footage dropped since holds the pixels from before) let since = c.since.as_ref().and_then(|s| s.for_cache(&dc)).filter(|s| !dc.dropped_since(files, *s))?; + // (only a frame that costs more to render again than to read back, #3301) + if !dc.pays_off(c.img.bytes(), c.cost_us) { + return None; + } let dk = disk_cache::frame_key(content, k.frame, k.scale, k.view ^ oh); let tries = written.1.get(&dk).copied().unwrap_or(0); (tries < 2 && !dc.contains(disk_cache::Kind::Frame, dk) && !dc.frame_pending(dk) && queued.insert(dk)) @@ -1763,8 +1769,11 @@ impl Worker { // and compression. Persistence still runs on this worker, using the same snapshot. let since = disk.as_ref().map(|(dc, _, since)| DiskSince::of(dc, *since)); self.finish(&job, ci.clone(), Some(files.clone()), since, t0); + let took_us = u64::try_from(t0.elapsed().as_micros()).unwrap_or(u64::MAX); if !disk_hit && let Some((dc, k, since)) = &disk + // (only a frame that costs more to render again than to read back, #3301) + && dc.pays_off(ci.bytes(), took_us) && put_disk_frame(dc, *k, &ci, &files, self.virtual_id.as_deref(), *since) && let Some(ctx) = &self.ctx { diff --git a/crates/ui-egui/src/frames/tests.rs b/crates/ui-egui/src/frames/tests.rs index fc0d1d028..5898cb5ba 100644 --- a/crates/ui-egui/src/frames/tests.rs +++ b/crates/ui-egui/src/frames/tests.rs @@ -2769,6 +2769,8 @@ mod frame_files { fn session(p: &Arc, dir: &Path) -> Session { let disk = DiskCache::open(dir.join("cache"), 1 << 30).unwrap(); + // (every frame is written, however quick to render: not decided by this machine's speed) + disk.set_read_us_per_mb(0); let hook_calls = Arc::new(AtomicUsize::new(0)); let mut frames = Frames::default(); let calls = hook_calls.clone(); @@ -3050,9 +3052,9 @@ fn the_accountant_trims_only_frames_in_ram() { assert_eq!(memory.bytes(), 16); } -/// #3298 review: preview frames compete with the other caches by value. A frame a playing -/// preview shows next counts as just used, and a frame rendered quickly (from cached layers) -/// still costs a typical render: an old, cheap footage frame goes before it. +/// #3301: frames a playing preview shows next are protected: other caches give way first, even +/// for items worth more, until the caches are more than the bounded overage over; past it the +/// preview frames go too. A frame rendered quickly still costs a typical render. #[test] fn preview_frames_ahead_of_the_playhead_outlive_old_footage() { use effectcraft_engine::render::memory::{self, Accountant, Candidate, MemoryHolder}; @@ -3077,26 +3079,26 @@ fn preview_frames_ahead_of_the_playhead_outlive_old_footage() { let mut c = frames.cache.lock().unwrap(); for i in 10..12 { c.insert_took(key(1, i, 0), img(), None, None, Some(std::time::Duration::from_micros(100))); - // (as old as the footage frame below) - c.map.get_mut(&key(1, i, 0)).unwrap().used = 0; } } let preview: Arc = Arc::new(PreviewMemory(frames.cache.clone())); - // Stopped: the oldest frame is offered as it is, with at least a typical render's cost. + // Stopped: the oldest frame is offered unprotected, with at least a typical render's cost. let offered = preview.oldest().unwrap(); - assert_eq!(offered.used, 0); + assert!(!offered.protected); assert_eq!(offered.cost_us, memory::default_cost(16, memory::DEFAULT_PREVIEW_US_PER_MB)); - // Playing from frame 10: the frames ahead count as just used. + // Playing from frame 10: the frames ahead are protected. frames.set_playhead(Some(playhead(10, false))); - let before = memory::tick(); - assert!(preview.oldest().unwrap().used >= before); - // An old footage frame that cost less per byte goes first. - let footage = Arc::new(Footage(Mutex::new(vec![Candidate { used: 0, bytes: 16, cost_us: 6_000 }]))); + assert!(preview.oldest().unwrap().protected); + // A footage frame worth far more per byte, used just now, still goes first. + let footage = Arc::new(Footage(Mutex::new(vec![Candidate::new(memory::tick(), 16, 1_000_000)]))); let footage_holder: Arc = footage.clone(); - let acc = Accountant::new(40); + let acc = Accountant::new(1000); acc.register(&preview); acc.register(&footage_holder); - acc.balance(); + acc.set_budget(40); assert_eq!(footage.bytes(), 0, "the footage frame went"); - assert_eq!(preview.bytes(), 32, "the preview frames stay"); + assert_eq!(preview.bytes(), 32, "the preview frames stay, a bounded way over"); + // Far over the budget, past the overage: the preview frames go too. + acc.set_budget(10); + assert!(preview.bytes() < 32, "{}", preview.bytes()); } diff --git a/docs/preferences.md b/docs/preferences.md index 16c11bd2e..c5a3f4cdb 100644 --- a/docs/preferences.md +++ b/docs/preferences.md @@ -53,9 +53,11 @@ Commands (CLI, MCP, control channel): - `composition.showRenderingProgress`: Show Rendering Progress in Info Panel and Flowchart - `previews.adaptiveResolutionLimit`: Adaptive Resolution Limit (the lowest resolution Fast Previews ▸ Adaptive Resolution drops to while you drag; a playing preview keeps the viewer's resolution) -- `previews.cacheFramesWhenIdle`: Cache Frames When Idle (Composition ▸ Preview): after a second - without input or edits, the viewer renders the work area into the RAM preview in the - background, from the current time on, until it is cached or the budget is full +- `previews.cacheFramesWhenIdle`: Cache Frames When Idle (Composition ▸ Preview), on by default: + after a second without input or edits, the viewer renders the work area into the RAM preview + in the background, from the current time on, until it is cached or the budget is full. Any + input, edit, playback or a frame the viewer waits for stops it at once (it starts again after + the next quiet second). A saved setting of off stays off - `previews.fastPreviews`: Fast Previews (Draft 3D, Faster Effects) - `appearance.appearanceMode`: Appearance Mode (`auto` / `dark` / `light`). `auto` (Sync with System) follows the operating system's light or dark appearance while the app runs: on Linux the desktop app reads the XDG desktop portal (`org.freedesktop.appearance` `color-scheme`) once and then listens for its `SettingChanged` signal on a worker thread, repainting only when the value changes (nothing polls); `gsettings` runs at most once at start-up, by absolute path, when the portal gives no answer. Elsewhere it uses what the window system reports. With no answer it shows the dark theme. New installs stay `dark`; Sync with System is opt-in. The Tools bar's appearance button (a monitor, sun or moon) cycles Sync with System, Light and Dark (`view.theme.toggle`, Next Appearance Mode). - `appearance.darkTheme`: Dark Theme (`dark` / `darker`), shown in dark appearance @@ -171,10 +173,22 @@ Commands (CLI, MCP, control channel): hold more than the budget together, the memory accountant frees the least valuable data first, whichever cache holds it, down to 90 % of the budget. An item's value is what it would cost to make again (its measured render or decode time; when not measured, a typical 4 ms per MB for a - layer, 8 ms for a preview frame, 2 ms for footage frames and planes) per byte, halved after - 30 s unused, a quarter after 90 s, and so on; a copy of data another cache holds (a queued disk write) is worth - nothing, and a cache that had to make again what it let go of shortly before is protected for - a while. In the browser the layer cache also stays within 512 MB and the footage frames within + layer, 8 ms for a preview frame, 2 ms for footage frames and planes) per byte, divided by + `ln(seconds unused + 1) + 1`: a slow decay (about a fifth after a minute unused, a seventh after + ten), so a costly frame unused for minutes still outlives a cheap one; a copy of data another + cache holds (a queued disk write) is worth nothing, and a cache that had to make again what it + let go of shortly before is protected for a while. The frames a playing RAM preview shows next + go last: they may keep the caches over the budget by a tenth of it (at most 1 GB) while other + items can go instead. Besides the bytes the caches count, the process's measured memory is + watched (its resident size, read with each balance and at most every 250 ms): above 95 % of the + installed RAM left after the reserve the caches give way by what it is over even within their + budget (memory nobody counts: GPU staging, effect buffers, the allocator's fragmentation), at + most once per reading unless it grows; above all of it also the preview frames that would + play next. A frame or plane set is written to the disk cache only when making it again costs + more than reading it back (the measured read rate, 10 ms per MB until reads are measured); a + RAM eviction keeps the disk copy, and the disk cache drops its oldest entries first. At most + 256 movie and audio files are kept open, the least recently used closed beyond that (image + sequences, OpenEXR included, keep no file open between decodes). In the browser the layer cache also stays within 512 MB and the footage frames within 256 MB (see [web.md](web.md)). The Memory & CPU page shows what EffectCraft may use, of the installed RAM. Settings saved before this (version 4 and earlier) had Layer Cache, Footage Frame Cache and Preview (RAM) Cache budgets (`memory.layerCacheMb`, `memory.mediaCacheMb`,