Footage cache (#3271): one memory accountant over the big caches

render::memory::Accountant: one budget (the sum of the Memory & CPU budgets) over the holders
that register with it: the footage frames (priority 0), the disk write queue (0), the decoded
footage planes (1) and the layer cache (2). Over the budget it frees lowest priority first,
down to 90% of it; a holder that makes again what it just let go of (the layer cache tells its
refills) is protected while it thrashes. Holders are held weakly and balanced after their own
inserts, with their locks released.
This commit is contained in:
vangel76 committed 2026-11-08 03:05:18 +01:00
1 parent f33bfccc07
commit d4a86e037e
8 files changed
+538 -25

No files matched your search

+75 -23
View File
@@ -67,6 +67,37 @@ struct Inner {
/// a render's reads started at travels with its files instead, [`ReadFiles::since`]: two
/// renders of a key may overlap).
missed_at: HashMap<u64, web_time::Instant>,
/// Keys let go of lately (newest last, at most [`EVICTED_KEPT`]) and how many of them were
/// asked for again: a cache that keeps making again what it just let go of is thrashing
/// ([`crate::memory::MemoryHolder::refills`]).
evicted: std::collections::VecDeque<u64>,
refills: u64,
}
/// Keys of evicted buffers remembered to tell a refill (#3271).
const EVICTED_KEPT: usize = 256;
impl Inner {
/// Drop least recently used entries until at most `bytes` are held, remembering their keys.
fn evict_to(&mut self, bytes: usize) {
if self.bytes <= bytes {
return;
}
let mut by_age: Vec<(u64, u64)> = self.map.iter().map(|(k, e)| (e.last_use, *k)).collect();
by_age.sort_unstable();
for (_, k) in by_age {
if self.bytes <= bytes {
break;
}
if let Some(e) = self.map.remove(&k) {
self.bytes -= e.bytes;
if self.evicted.len() >= EVICTED_KEPT {
self.evicted.pop_front();
}
self.evicted.push_back(k);
}
}
}
}
/// Hit/miss counters and memory use (for perf readouts and tests).
@@ -88,7 +119,17 @@ impl LayerCache {
/// A cache holding at most `budget` bytes of pixels.
pub fn new(budget: usize) -> LayerCache {
LayerCache {
inner: Mutex::new(Inner { map: HashMap::new(), bytes: 0, budget, clock: 0, hits: 0, misses: 0, missed_at: HashMap::new() }),
inner: Mutex::new(Inner {
map: HashMap::new(),
bytes: 0,
budget,
clock: 0,
hits: 0,
misses: 0,
missed_at: HashMap::new(),
evicted: Default::default(),
refills: 0,
}),
disk: Mutex::new(None),
store: Mutex::new(None),
virtual_id: Mutex::new(None),
@@ -162,6 +203,11 @@ impl LayerCache {
None => {
let mut g = self.inner.lock().ok()?;
g.misses += 1;
// (made again shortly after it was let go of: a refill)
if let Some(at) = g.evicted.iter().position(|k| *k == key) {
g.evicted.remove(at);
g.refills += 1;
}
drop(g);
let store = self.persistent();
// (before the entry is read: what it is made of may be dropped meanwhile)
@@ -299,17 +345,11 @@ impl LayerCache {
if g.bytes > g.budget {
// Evict least-recently used entries down to 3/4 of the budget.
let target = g.budget / 4 * 3;
let mut by_age: Vec<(u64, u64)> = g.map.iter().map(|(k, e)| (e.last_use, *k)).collect();
by_age.sort_unstable();
for (_, k) in by_age {
if g.bytes <= target {
break;
}
if let Some(e) = g.map.remove(&k) {
g.bytes -= e.bytes;
}
}
g.evict_to(target);
}
drop(g);
// (with the lock released: the accountant asks every cache for its bytes)
crate::memory::Accountant::global().balance();
(buf, files)
}
@@ -322,18 +362,7 @@ impl LayerCache {
pub fn set_budget(&self, budget: usize) {
let Ok(mut g) = self.inner.lock() else { return };
g.budget = budget;
if g.bytes > budget {
let mut by_age: Vec<(u64, u64)> = g.map.iter().map(|(k, e)| (e.last_use, *k)).collect();
by_age.sort_unstable();
for (_, k) in by_age {
if g.bytes <= budget {
break;
}
if let Some(e) = g.map.remove(&k) {
g.bytes -= e.bytes;
}
}
}
g.evict_to(budget);
}
pub fn clear(&self) {
@@ -945,6 +974,29 @@ pub fn derive(key: u64, i: u64) -> u64 {
h.finish()
}
/// The layer cache in the common memory budget (#3271): rendered layer buffers, costly to make
/// again, are freed after footage frames and planes.
impl crate::memory::MemoryHolder for LayerCache {
fn name(&self) -> &'static str {
"layer cache"
}
fn bytes(&self) -> usize {
self.inner.lock().map(|g| g.bytes).unwrap_or(0)
}
fn priority(&self) -> u8 {
2
}
fn trim_to(&self, bytes: usize) {
if let Ok(mut g) = self.inner.lock() {
g.evict_to(bytes);
}
}
fn refills(&self) -> u64 {
self.inner.lock().map(|g| g.refills).unwrap_or(0)
}
}
#[cfg(test)]
mod shared_insert_tests {
use std::sync::Arc;
+47
View File
@@ -440,6 +440,15 @@ impl Queue {
fn is_empty(&self) -> bool {
self.frames.is_empty() && self.jobs.is_empty()
}
/// The bytes the queued writes hold.
fn held_bytes(&self) -> usize {
let job = |j: &Job| match j {
Job::Write(_, _, _, p) => p.held(),
Job::Drop(_) => 0,
};
self.frames.iter().chain(&self.jobs).map(job).fold(0, usize::saturating_add)
}
}
pub struct DiskCache {
@@ -1442,6 +1451,44 @@ impl effectcraft_effects::roto::SegStore for DiskCache {
}
}
/// The disk cache's write queue in the common memory budget (#3271): queued entries hold their
/// pixels until the writer has written them. The first freed (a dropped write only costs a
/// later render a disk miss); frames are kept over layer buffers.
impl crate::memory::MemoryHolder for DiskCache {
fn name(&self) -> &'static str {
"disk write queue"
}
fn bytes(&self) -> usize {
self.queue.0.lock().map(|q| q.held_bytes()).unwrap_or(0)
}
fn priority(&self) -> u8 {
0
}
fn trim_to(&self, bytes: usize) {
let Ok(mut q) = self.queue.0.lock() else { return };
while q.held_bytes() > bytes {
// Layer and plane writes first (newest first), then frames.
let job = match q.jobs.iter().rposition(|j| matches!(j, Job::Write(..))) {
Some(i) => q.jobs.remove(i),
None => match q.frames.pop_back() {
Some(j) => {
if let Job::Write(_, key, _, p) = &j {
q.frame_bytes = q.frame_bytes.saturating_sub(p.held());
q.pending_frames.remove(key);
}
Some(j)
}
None => None,
},
};
if job.is_none() {
break;
}
self.dropped.fetch_add(1, Ordering::Relaxed);
}
}
}
impl crate::cache::LayerStore for DiskCache {
/// The layer for `key` from the disk cache, or `None` when it is missing or stale.
fn get_layer(&self, key: u128, virtual_id: Option<VirtualFileId<'_>>) -> Option<(Arc<Buf>, ReadFiles)> {
+1
View File
@@ -16,6 +16,7 @@ pub mod disk_cache;
use color::Region;
pub mod eval;
pub mod masks;
pub mod memory;
pub mod passes;
pub mod reads;
pub mod shapes;
+283
View File
@@ -0,0 +1,283 @@
//! One memory accountant for the big caches (#3271): the layer cache, the media pool's frames,
//! the decoded footage planes and the preview frames each keep their own budget, and register
//! here as [`MemoryHolder`]s. When all of them together hold more than the one budget
//! ([`Accountant::set_budget`], the sum of Settings ▸ Memory & CPU's budgets), the accountant
//! frees from the lowest priority first, in large steps: down to [`TRIM_TO`] of the budget, so
//! a cache doesn't fill up and trim again with every insert.
//!
//! A holder that had to make again what it let go of shortly before (its "refills",
//! [`MemoryHolder::refills`]) is thrashing: its priority goes up by one until it settles, so the
//! data that is needed again is kept longest.
//!
//! Holders are held weakly: a cache that goes away is forgotten. The accountant never calls a
//! holder while it holds its own lock, and holders call [`Accountant::balance`] after releasing
//! theirs.
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::{Arc, Mutex, PoisonError, Weak};
/// The share of the budget the accountant frees down to once it is over (hysteresis).
pub const TRIM_TO: f64 = 0.9;
/// A cache the accountant keeps within the common budget.
pub trait MemoryHolder: Send + Sync {
/// A name for logs and stats.
fn name(&self) -> &'static str;
/// The bytes it holds now.
fn bytes(&self) -> usize;
/// How valuable its data is: lower is freed first (a copy of what another cache holds,
/// then what is cheap to make again, then what is expensive).
fn priority(&self) -> u8;
/// Free its least valuable data until it holds at most `bytes` (data in use may stay).
fn trim_to(&self, bytes: usize);
/// How many times so far it made again what it had let go of shortly before (0 when it
/// doesn't tell).
fn refills(&self) -> u64 {
0
}
}
struct Registered {
holder: Weak<dyn MemoryHolder>,
/// Its refills at the last balance, and whether it was thrashing then.
refills: u64,
thrashing: bool,
}
/// The common budget of the big caches (see the module notes).
pub struct Accountant {
budget: AtomicUsize,
holders: Mutex<Vec<Registered>>,
/// Bytes freed by the accountant so far (stats, tests).
freed: AtomicUsize,
}
impl Default for Accountant {
fn default() -> Self {
Accountant::new(usize::MAX)
}
}
impl Accountant {
/// An accountant with `budget` bytes (`usize::MAX`: no limit).
pub const fn new(budget: usize) -> Accountant {
Accountant { budget: AtomicUsize::new(budget), holders: Mutex::new(Vec::new()), freed: AtomicUsize::new(0) }
}
/// The process's accountant.
pub fn global() -> &'static Accountant {
static GLOBAL: Accountant = Accountant::new(usize::MAX);
&GLOBAL
}
/// Set the common budget and free down to it at once.
pub fn set_budget(&self, bytes: usize) {
self.budget.store(bytes, Ordering::Relaxed);
self.balance();
}
pub fn budget(&self) -> usize {
self.budget.load(Ordering::Relaxed)
}
/// Keep `holder` within the common budget (held weakly).
pub fn register(&self, holder: &Arc<dyn MemoryHolder>) {
let mut h = self.holders.lock().unwrap_or_else(PoisonError::into_inner);
h.retain(|r| r.holder.strong_count() > 0);
let weak = Arc::downgrade(holder);
// (registered again with each new budget: once is enough)
if h.iter().any(|r| r.holder.ptr_eq(&weak)) {
return;
}
h.push(Registered { holder: weak, refills: holder.refills(), thrashing: false });
}
/// The holders alive now, with their effective priority (raised while thrashing).
fn alive(&self) -> Vec<(Arc<dyn MemoryHolder>, u8)> {
let mut h = self.holders.lock().unwrap_or_else(PoisonError::into_inner);
h.retain(|r| r.holder.strong_count() > 0);
h.iter_mut()
.filter_map(|r| {
let holder = r.holder.upgrade()?;
let refills = holder.refills();
r.thrashing = refills > r.refills;
r.refills = refills;
let p = holder.priority().saturating_add(u8::from(r.thrashing));
Some((holder, p))
})
.collect()
}
/// The bytes all holders hold now.
pub fn total(&self) -> usize {
let h = self.holders.lock().unwrap_or_else(PoisonError::into_inner);
let alive: Vec<Arc<dyn MemoryHolder>> = h.iter().filter_map(|r| r.holder.upgrade()).collect();
drop(h);
alive.iter().map(|h| h.bytes()).fold(0, usize::saturating_add)
}
/// Bytes freed by the accountant so far.
pub fn freed(&self) -> usize {
self.freed.load(Ordering::Relaxed)
}
/// When the holders together are over the budget, free down to [`TRIM_TO`] of it, lowest
/// priority first (a holder is trimmed as far as needed before the next one is touched).
pub fn balance(&self) {
let budget = self.budget();
if budget == usize::MAX {
return;
}
let mut holders = self.alive();
let mut total: usize = holders.iter().map(|(h, _)| h.bytes()).fold(0, usize::saturating_add);
if total <= budget {
return;
}
let target = (budget as f64 * TRIM_TO) as usize;
holders.sort_by_key(|(_, p)| *p);
for (h, _) in holders {
if total <= target {
break;
}
let had = h.bytes();
let over = total - target;
h.trim_to(had.saturating_sub(over));
let now = h.bytes();
let freed = had.saturating_sub(now);
total = total.saturating_sub(freed);
self.freed.fetch_add(freed, Ordering::Relaxed);
}
}
}
#[cfg(test)]
mod tests {
use super::*;
/// A holder of `bytes` in blocks of `step`, trimmed whole blocks at a time.
struct Fake {
name: &'static str,
bytes: Mutex<usize>,
step: usize,
priority: u8,
refills: Mutex<u64>,
}
impl Fake {
fn new(name: &'static str, bytes: usize, priority: u8) -> Arc<Fake> {
Arc::new(Fake { name, bytes: Mutex::new(bytes), step: 10, priority, refills: Mutex::new(0) })
}
fn held(&self) -> usize {
*self.bytes.lock().unwrap()
}
fn fill(&self, more: usize) {
*self.bytes.lock().unwrap() += more;
}
}
impl MemoryHolder for Fake {
fn name(&self) -> &'static str {
self.name
}
fn bytes(&self) -> usize {
self.held()
}
fn priority(&self) -> u8 {
self.priority
}
fn trim_to(&self, bytes: usize) {
let mut b = self.bytes.lock().unwrap();
while *b > bytes {
*b = b.saturating_sub(self.step);
}
}
fn refills(&self) -> u64 {
*self.refills.lock().unwrap()
}
}
fn holder(f: &Arc<Fake>) -> Arc<dyn MemoryHolder> {
f.clone()
}
/// Over the budget, the lowest priority is freed first, down to 90% of the budget; under it,
/// nothing is touched.
#[test]
fn lowest_priority_goes_first_down_to_the_trim_line() {
let acc = Accountant::new(1000);
let (planes, frames, layers) = (Fake::new("planes", 300, 0), Fake::new("frames", 400, 1), Fake::new("layers", 300, 2));
let held: Vec<Arc<dyn MemoryHolder>> = vec![holder(&layers), holder(&planes), holder(&frames)];
for h in &held {
acc.register(h);
}
acc.balance();
assert_eq!((planes.held(), frames.held(), layers.held()), (300, 400, 300), "at the budget: nothing freed");
frames.fill(200);
acc.balance();
// 1200 held, down to 900: the planes go first (300), then frames give the rest.
assert_eq!((planes.held(), frames.held(), layers.held()), (0, 600, 300));
assert_eq!(acc.total(), 900);
assert_eq!(acc.freed(), 300);
// A little over again: freed in one step down to 900, not by the few bytes over.
layers.fill(110);
acc.balance();
assert_eq!(acc.total(), 900);
}
/// A holder that makes again what it let go of is kept longer: its priority goes up while it
/// thrashes.
#[test]
fn a_thrashing_holder_is_protected() {
let acc = Accountant::new(1000);
let (cheap, other) = (Fake::new("cheap", 600, 0), Fake::new("other", 600, 0));
let held: Vec<Arc<dyn MemoryHolder>> = vec![holder(&cheap), holder(&other)];
for h in &held {
acc.register(h);
}
*cheap.refills.lock().unwrap() += 3;
acc.balance();
assert_eq!(cheap.held(), 600, "thrashing: kept");
assert_eq!(other.held(), 300);
}
/// Holders that went away are forgotten; no budget means nothing is freed.
#[test]
fn holders_are_held_weakly() {
let acc = Accountant::new(10);
{
let gone = Fake::new("gone", 500, 0);
acc.register(&holder(&gone));
}
assert_eq!(acc.total(), 0);
let free = Accountant::default();
let kept = Fake::new("kept", 500, 0);
free.register(&holder(&kept));
free.balance();
assert_eq!(kept.held(), 500);
}
/// The layer cache as a holder: trimmed least recently used first, and a buffer asked for
/// again after the accountant let it go counts as a refill, which protects the cache.
#[test]
fn the_layer_cache_is_trimmed_and_tells_refills() {
use effectcraft_effects::Buf;
use effectcraft_raster::Image;
let cache = Arc::new(crate::cache::LayerCache::new(1 << 30));
let one = 8 * 8 * std::mem::size_of::<effectcraft_raster::Px>();
for k in 0..4u64 {
cache.insert(k, Arc::new(Buf { img: Image::new(8, 8), offset: [0.0; 2], scale: 1.0 }), Default::default());
}
let acc = Accountant::new(2 * one);
let layers: Arc<dyn MemoryHolder> = cache.clone();
acc.register(&layers);
acc.balance();
assert!(layers.bytes() <= (2.0 * one as f64 * TRIM_TO) as usize, "{}", layers.bytes());
assert!(cache.get(0).is_none(), "the oldest went first");
assert_eq!(layers.refills(), 1, "asked for again after it was let go of");
// Thrashing: a holder of the same priority is freed before it.
let other = Fake::new("other", 2 * one, 2);
acc.register(&holder(&other));
acc.balance();
assert!(other.held() < 2 * one, "the other holder gave way");
}
}