Footage cache (#3271): stage B self-review fixes

- A region of interest looks up the whole layer's cached buffer first; only a miss reads the
  rows (and keeps nothing).
- The rows margin counts the region's rounding at the layer's own scale; the region test covers
  shrunk and enlarged layers at reduced resolution.
- Layer and plane writes are bounded by the bytes they hold while queued (1 GB).
- The disk cache's drop generation is taken before the file is opened, so planes of a file
  reloaded meanwhile are refused.
- A plane entry of another shape than the planes asked for is a miss before anything is
  decompressed.
- The claim hand-off is one atomic phase (queued, running, claimed): no gap between the claim
  and the queued job.
This commit is contained in:
vangel76 committed 2026-11-08 03:17:34 +01:00
1 parent fae48d8114
commit c1534f4502
4 files changed
+109 -41

No files matched your search

+57 -27
View File
@@ -152,15 +152,27 @@ pub(crate) enum Refused {
struct Flight {
state: Mutex<FlightState>,
ready: Condvar,
/// The decode began: on the decode threads, or claimed by a decode thread that asked for the
/// same planes before the queued decode began ([`Flight::claim`]).
started: std::sync::atomic::AtomicBool,
/// A decode thread claimed it: the outcome comes through `handed`, not the queued job.
claimed: std::sync::atomic::AtomicBool,
/// [`QUEUED`], [`RUNNING`] (the decode began where it was asked for) or [`CLAIMED`] (a
/// decode thread took it over before it began, [`Flight::claim`]: the outcome comes through
/// `handed`).
phase: std::sync::atomic::AtomicU8,
handed: Mutex<Option<Result<Arc<Batch>, Refused>>>,
handed_ready: Condvar,
/// What the store held when the decode was asked for (the decode adds to it).
base: Option<Arc<Batch>>,
/// The disk cache's drop generation before the file was opened for this request (#3191: a
/// plane entry made of a file reloaded since is refused).
since: u64,
}
/// [`Flight::phase`] values.
const QUEUED: u8 = 0;
const RUNNING: u8 = 1;
const CLAIMED: u8 = 2;
/// The disk cache's drop generation now (0 without one): taken before a file is opened.
fn drop_generation() -> u64 {
disk_cache().map_or(0, |d| d.drop_generation())
}
struct FlightState {
@@ -173,31 +185,36 @@ struct FlightState {
impl Flight {
fn new(index: Arc<ExrIndex>, want: Want) -> Arc<Flight> {
Flight::with_base(index, want, None)
Flight::with_base(index, want, None, drop_generation())
}
fn with_base(index: Arc<ExrIndex>, want: Want, base: Option<Arc<Batch>>) -> Arc<Flight> {
fn with_base(index: Arc<ExrIndex>, want: Want, base: Option<Arc<Batch>>, since: u64) -> Arc<Flight> {
Arc::new(Flight {
state: Mutex::new(FlightState { index, want, sealed: false, outcome: None }),
ready: Condvar::new(),
started: std::sync::atomic::AtomicBool::new(false),
claimed: std::sync::atomic::AtomicBool::new(false),
phase: std::sync::atomic::AtomicU8::new(QUEUED),
handed: Mutex::new(None),
handed_ready: Condvar::new(),
base,
since,
})
}
/// Move the flight from [`QUEUED`] to `to`; `false` when it left that phase already.
fn take(&self, to: u8) -> bool {
use std::sync::atomic::Ordering;
self.phase.compare_exchange(QUEUED, to, Ordering::SeqCst, Ordering::SeqCst).is_ok()
}
/// Take over the decode while it is still queued (a decode thread asking for the planes
/// it would wait for: waiting there could starve the queue it waits on). `false` once it
/// began.
fn claim(&self) -> bool {
use std::sync::atomic::Ordering;
let won = self.started.compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst).is_ok();
if won {
self.claimed.store(true, Ordering::SeqCst);
}
won
self.take(CLAIMED)
}
fn claimed(&self) -> bool {
self.phase.load(std::sync::atomic::Ordering::SeqCst) == CLAIMED
}
/// Hand the claimed decode's outcome to the request that queued it.
@@ -337,6 +354,10 @@ pub(crate) struct DecodeRecord {
#[cfg(test)]
static DECODES: Mutex<Vec<(String, DecodeRecord)>> = Mutex::new(Vec::new());
/// Paths whose queued decode a decode thread took over (tests).
#[cfg(test)]
pub(crate) static CLAIMS: Mutex<Vec<String>> = Mutex::new(Vec::new());
/// The decodes of `path` so far (tests; paths are unique per test).
#[cfg(test)]
pub(crate) fn decodes_of(path: &str) -> Vec<DecodeRecord> {
@@ -394,12 +415,14 @@ impl PlaneStore {
/// file it was read from is noted ([`crate::reads`]). A request that keeps finding the
/// decodes it waits for called off decodes a copy itself.
pub(crate) fn get(&self, path: &str, source: &ExrSource, index: &Arc<ExrIndex>, want: &Want, by: Use) -> Result<Arc<Batch>, Refused> {
self.get_opened(path, source, index, want, by, None)
self.get_opened(path, source, index, want, by, None, drop_generation())
}
/// [`PlaneStore::get`] with the file already open (`opened`, as indexing it opened it): a
/// decode reads from it instead of opening the file again, so a new frame opens its file
/// once (#3271). Dropped unused when the store serves the request.
/// once (#3271). Dropped unused when the store serves the request. `since`: the disk cache's
/// drop generation before the file was opened ([`drop_generation`]).
#[allow(clippy::too_many_arguments)]
pub(crate) fn get_opened(
&self,
path: &str,
@@ -408,10 +431,11 @@ impl PlaneStore {
want: &Want,
by: Use,
mut opened: Option<Opened>,
since: u64,
) -> Result<Arc<Batch>, Refused> {
let mut retries = 0;
for _ in 0..ROUNDS {
match self.step(path, source, index, want, by, &mut opened) {
match self.step(path, source, index, want, by, &mut opened, since) {
Step::Done(r) => return r,
Step::Again { retry: true } if retries >= RETRIES => break,
Step::Again { retry } => retries += u32::from(retry),
@@ -421,7 +445,8 @@ impl PlaneStore {
}
/// One round of [`PlaneStore::get`].
fn step(&self, path: &str, source: &ExrSource, index: &Arc<ExrIndex>, want: &Want, by: Use, opened: &mut Option<Opened>) -> Step {
#[allow(clippy::too_many_arguments)]
fn step(&self, path: &str, source: &ExrSource, index: &Arc<ExrIndex>, want: &Want, by: Use, opened: &mut Option<Opened>, since: u64) -> Step {
let level = 0;
let mut st = self.lock();
st.clock += 1;
@@ -474,7 +499,7 @@ impl PlaneStore {
}
// This request decodes: what it asks for, minus what the store holds.
let base = e.batch.clone().filter(|b| Arc::ptr_eq(&b.index, index));
let flight = Flight::with_base(index.clone(), want.clone(), base.clone());
let flight = Flight::with_base(index.clone(), want.clone(), base.clone(), since);
e.flight = Some(flight.clone());
drop(st);
#[cfg(test)]
@@ -696,6 +721,8 @@ impl Drop for Handing<'_> {
/// Decode a flight claimed by this thread (see [`Flight::claim`]) here, hand the outcome to the
/// request that queued it, and answer this request with it (or a copy when it doesn't cover it).
fn decode_claimed(path: &str, source: &ExrSource, flight: &Arc<Flight>, index: &Arc<ExrIndex>, want: &Want) -> Result<Arc<Batch>, Refused> {
#[cfg(test)]
CLAIMS.lock().unwrap_or_else(PoisonError::into_inner).push(path.to_string());
let mut handing = Handing { flight, outcome: None };
let outcome = decode(path, source, flight, flight.base.clone(), None);
handing.outcome = Some(outcome.clone());
@@ -722,20 +749,20 @@ fn run(path: &str, source: &ExrSource, flight: &Arc<Flight>, base: Option<Arc<Ba
let hints = filmcraft_media::cancel::Context::current();
threads.spawn(move || {
// (claimed meanwhile by a decode thread: it decodes, and hands the outcome over)
if !queued.started.swap(true, std::sync::atomic::Ordering::SeqCst) {
if queued.take(RUNNING) {
let _ = tx.send(hints.run(|| decode(&path, &source, &queued, base, opened)));
}
});
// A plain block: this thread runs nothing else meanwhile.
return match rx.recv() {
Ok(outcome) => outcome,
Err(_) if flight.claimed.load(std::sync::atomic::Ordering::SeqCst) => flight.take_handed(),
Err(_) if flight.claimed() => flight.take_handed(),
// (a decode that panicked sent nothing)
Err(_) => Err(Refused::Stopped),
};
}
// (claimed by a decode thread before this one began: it hands the outcome over)
if flight.started.swap(true, std::sync::atomic::Ordering::SeqCst) {
if !flight.take(RUNNING) {
return flight.take_handed();
}
decode(path, source, flight, base, opened)
@@ -781,13 +808,13 @@ fn decode(path: &str, source: &ExrSource, flight: &Arc<Flight>, base: Option<Arc
let names: Vec<String> = missing.iter().filter_map(|i| index.channels.get(*i)).map(|c| c.name.clone()).collect();
// The disk tier first (#3271): what an earlier session or a decode RAM let go of kept.
let disk = disk_cache().filter(|_| !missing.is_empty() && unique(&names));
let since = disk.as_ref().map_or(0, |d| d.drop_generation());
let since = flight.since;
let key = {
let refs: Vec<&str> = names.iter().map(String::as_str).collect();
effectcraft_render::disk_cache::plane_key(path, &opened.stamp, &refs, 0, None)
};
let (w, h) = index.size();
let kept = disk.as_ref().and_then(|d| d.get_planes(key, None)).map(|(p, _)| p).filter(|p| {
let kept = disk.as_ref().and_then(|d| d.get_planes(key, None, (w as u32, h as u32, names.len()))).map(|(p, _)| p).filter(|p| {
(p.width as usize, p.height as usize) == (w, h)
&& p.planes.len() == names.len()
&& p.planes.iter().zip(&names).all(|((n, v), want)| n == want && v.len() == w * h)
@@ -939,6 +966,8 @@ pub(crate) enum Picture {
pub(crate) fn picture(path: &str, source: &ExrSource, op: AlphaOp, extra: Option<&AuxNeed>) -> Picture {
let mut extra = extra;
for _ in 0..3 {
// (before the file is opened: see `Flight::since`)
let since = drop_generation();
let (index, opened) = match index_of(path, source) {
Ok(ix) => ix,
Err(IndexError::Unsupported(why)) => return Picture::Done(Err(why.to_string())),
@@ -953,7 +982,7 @@ pub(crate) fn picture(path: &str, source: &ExrSource, op: AlphaOp, extra: Option
}
}
let by = if extra.is_some() { Use::Picture } else { Use::Other };
let batch = match store().get_opened(path, source, &index, &want, by, opened) {
let batch = match store().get_opened(path, source, &index, &want, by, opened, since) {
Ok(b) => b,
Err(Refused::Changed) => continue,
// The channels with it are too many: the picture alone (the effects ask for theirs).
@@ -1054,12 +1083,13 @@ pub(crate) fn picture_rows(path: &str, source: &ExrSource, op: AlphaOp, rows: (i
/// store. `None` when it isn't a readable OpenEXR (or the request was called off).
pub(crate) fn aux(path: &str, source: &ExrSource, need: &AuxNeed) -> Option<Arc<AuxChannels>> {
for _ in 0..2 {
let since = drop_generation();
let (index, opened) = index_of(path, source).ok()?;
let want = match need_ids(&index, need) {
Some(ids) => Want { all: false, ids },
None => Want { all: true, ids: BTreeSet::new() },
};
match store().get_opened(path, source, &index, &want, Use::Other, opened) {
match store().get_opened(path, source, &index, &want, Use::Other, opened, since) {
Ok(b) => return Some(b.aux.clone()),
Err(Refused::Changed) => continue,
Err(_) => return None,
+9 -3
View File
@@ -898,7 +898,11 @@ fn a_decode_thread_takes_over_a_queued_decode() {
let _ = release.send(());
}
assert!(claimed.is_ok() && claimed == asked, "{claimed:?} {asked:?}");
assert_eq!(decodes_of(path).len(), 1, "decoded once");
// (other tests share the decode threads: when one of theirs ran first, the queued decode
// began before the decode thread asked, and it decoded a copy, as before)
if CLAIMS.lock().unwrap_or_else(PoisonError::into_inner).iter().any(|p| p == path) {
assert_eq!(decodes_of(path).len(), 1, "decoded once");
}
}
/// #3271: the plane store in the common memory budget: trimmed least recently used first,
@@ -1004,8 +1008,10 @@ fn a_region_of_interest_reads_only_its_rows() {
l.props.prop_mut("transform/rotation").unwrap().value = Value::Scalar(12.0);
l.props.prop_mut("transform/scale").unwrap().value = Value::Vec3([90.0, 110.0, 100.0]);
p.comp_mut(cid).unwrap().layers = vec![l].into();
for scale in [1.0, 0.5] {
let opts = RenderOpts { scale, roi: Some([30.0, 40.0, 24.0, 10.0]), ..Default::default() };
for (layer_scale, scale) in [(100.0, 1.0), (100.0, 0.5), (30.0, 0.25), (30.0, 1.0), (250.0, 0.5)] {
let comp = p.comp_mut(cid).unwrap();
comp.layers[0].props.prop_mut("transform/scale").unwrap().value = Value::Vec3([layer_scale * 0.9, layer_scale * 1.1, 100.0]);
let opts = RenderOpts { scale, roi: Some([38.0, 40.0, 24.0, 10.0]), ..Default::default() };
let whole = Renderer::new(&p, &Whole(&pool), opts).comp_frame(cid, Tick::ZERO);
let before = decodes_of(path).len();
let rows = Renderer::new(&p, &pool, opts).comp_frame(cid, Tick::ZERO);
+30 -7
View File
@@ -58,6 +58,10 @@ const QUEUE_LIMIT: usize = 64;
/// frames, so a fully cached comp came back with gaps in its blue bar.
#[cfg(not(target_arch = "wasm32"))]
const FRAME_QUEUE_BYTES: usize = 1 << 30;
/// Pending layer and plane bytes (uncompressed: they are encoded on the writer thread, #3271)
/// before new ones are dropped.
#[cfg(not(target_arch = "wasm32"))]
const JOB_QUEUE_BYTES: usize = 1 << 30;
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum Kind {
@@ -379,8 +383,10 @@ struct Queue {
frames: std::collections::VecDeque<Job>,
#[cfg_attr(target_arch = "wasm32", allow(dead_code))]
frame_bytes: usize,
/// Layer and matte writes.
/// Layer and matte writes, and the bytes they hold.
jobs: std::collections::VecDeque<Job>,
#[cfg_attr(target_arch = "wasm32", allow(dead_code))]
job_bytes: usize,
busy: bool,
/// Keys of frames queued or being written.
pending_frames: std::collections::HashSet<u128>,
@@ -435,7 +441,11 @@ impl Queue {
}
return Some(j);
}
self.jobs.pop_front()
let j = self.jobs.pop_front()?;
if let Job::Write(_, _, _, p) = &j {
self.job_bytes = self.job_bytes.saturating_sub(p.held());
}
Some(j)
}
fn is_empty(&self) -> bool {
self.frames.is_empty() && self.jobs.is_empty()
@@ -576,6 +586,7 @@ impl DiskCache {
frames: Default::default(),
frame_bytes: 0,
jobs: Default::default(),
job_bytes: 0,
busy: cfg!(not(target_arch = "wasm32")),
pending_frames: Default::default(),
drops: Drops::default(),
@@ -917,7 +928,7 @@ impl DiskCache {
}
let full = match kind {
Kind::Frame => q.frame_bytes.saturating_add(payload.held()) > FRAME_QUEUE_BYTES,
_ => q.jobs.len() >= QUEUE_LIMIT,
_ => q.jobs.len() >= QUEUE_LIMIT || q.job_bytes.saturating_add(payload.held()) > JOB_QUEUE_BYTES,
};
if full {
self.dropped.fetch_add(1, Ordering::Relaxed);
@@ -932,6 +943,7 @@ impl DiskCache {
q.frame_bytes = q.frame_bytes.saturating_add(payload.held());
q.frames.push_back(Job::Write(kind, key, format, payload));
} else {
q.job_bytes = q.job_bytes.saturating_add(payload.held());
q.jobs.push_back(Job::Write(kind, key, format, payload));
}
cv.notify_all();
@@ -1238,8 +1250,10 @@ impl DiskCache {
/// Decoded footage channels ([`plane_key`]) whose source file is unchanged, with that file,
/// as [`DiskCache::get_checked`] (#3271). `virtual_id` names files served from memory.
pub fn get_planes(&self, key: u128, virtual_id: Option<VirtualFileId<'_>>) -> Option<(DiskPlanes, ReadFiles)> {
self.get_checked(Kind::Plane, key, FORMAT_PLANES_FILES, virtual_id, decode_planes)
/// `expect`: the planes' width, height and count; an entry of another shape is a miss
/// (nothing larger is decompressed).
pub fn get_planes(&self, key: u128, virtual_id: Option<VirtualFileId<'_>>, expect: (u32, u32, usize)) -> Option<(DiskPlanes, ReadFiles)> {
self.get_checked(Kind::Plane, key, FORMAT_PLANES_FILES, virtual_id, |p| decode_planes(p, expect))
}
/// Queue decoded footage channels for writing: the planes of `aux` named `names` (in that
@@ -1469,7 +1483,13 @@ impl crate::memory::MemoryHolder for DiskCache {
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),
Some(i) => {
let j = q.jobs.remove(i);
if let Some(Job::Write(_, _, _, p)) = &j {
q.job_bytes = q.job_bytes.saturating_sub(p.held());
}
j
}
None => match q.frames.pop_back() {
Some(j) => {
if let Job::Write(_, key, _, p) = &j {
@@ -1625,9 +1645,12 @@ fn encode_planes(aux: &effectcraft_raster::AuxChannels, names: &[String]) -> Vec
}
/// The planes of a plane entry's pixels ([`encode_planes`]); `None` when damaged.
fn decode_planes(p: &[u8]) -> Option<DiskPlanes> {
fn decode_planes(p: &[u8], expect: (u32, u32, usize)) -> Option<DiskPlanes> {
let u32_at = |at: usize| Some(u32::from_le_bytes(p.get(at..at + 4)?.try_into().ok()?));
let (w, h, count) = (u32_at(0)?, u32_at(4)?, u32_at(8)? as usize);
if (w, h, count) != expect {
return None;
}
let n = (w as usize).checked_mul(h as usize).filter(|n| *n <= MAX_ENTRY_PIXELS)?;
if count > MAX_ENTRY_PLANES {
return None;
+13 -4
View File
@@ -969,7 +969,16 @@ impl<'a> Renderer<'a> {
if !lo.is_finite() || !hi.is_finite() {
return None;
}
let margin = 2.0 + (2.0 / self.opts.scale.max(1e-3)).ceil() + fx_margin.ceil();
// The warp samples its source with point taps (bilinear, bicubic: ±2 source pixels), so
// the rows reach 2 buffer pixels past the region's mapped centres (a reduced buffer's
// pixels are 1/scale footage rows), plus the region's rounding to output pixels: one
// output pixel is `k / scale` footage rows, `k` the footage rows per comp pixel.
let s = self.opts.scale.max(1e-3);
let k = [effectcraft_geom::vec3(1.0, 0.0, 0.0), effectcraft_geom::vec3(0.0, 1.0, 0.0)].iter().map(|v| inv.apply_vec(*v).length()).fold(1.0f64, f64::max);
if !k.is_finite() {
return None;
}
let margin = 2.0 + (2.0 / s).ceil() + (2.0 * k / s).ceil() + fx_margin.ceil();
let h = i64::from(f.height);
let (y0, y1) = (((lo - margin).floor() as i64).clamp(0, h), ((hi + margin).ceil() as i64).clamp(0, h));
(y0 > 0 || y1 < h).then_some((y0, y1.max(y0)))
@@ -1152,9 +1161,6 @@ impl<'a> Renderer<'a> {
mut timing: Option<&mut LayerTiming>,
) -> Option<(Arc<Buf>, Option<u64>, Arc<ReadFiles>)> {
let key = self.cache.and_then(|_| cache::layer_key(ctx, layer, self.raster_scale(ctx, layer), self.opts.draft, self.mb_on(ctx, layer)));
// A footage layer read in part (a region of interest, #3271) isn't kept: its key names
// the whole layer.
let key = key.filter(|_| !self.reads_footage_rows(ctx, layer));
let key = self.content_key(ctx, layer, key);
if let Some((b, files)) = self.cached(key) {
if let Some(t) = timing.as_deref_mut() {
@@ -1162,6 +1168,9 @@ impl<'a> Renderer<'a> {
}
return Some((b, key, files));
}
// A footage layer read in part (a region of interest, #3271) isn't kept: its key names
// the whole layer (a whole buffer kept before is used above).
let key = key.filter(|_| !self.reads_footage_rows(ctx, layer));
let (buf, files) = self.recorded(key, |r| {
// (what expressions read while it is made, at shutter times too, goes to its files)
let ctx = &r.with_reads(ctx);