Exports, the Render Queue and command-line renders use the memory budget (#3941)

The command-line tool reads the system's memory once at start, so its caches
share the budget of the installed RAM instead of the budget for unknown RAM.
A Render Queue run's two layer caches and a one-off export's own caches take
the session's layer cache budget instead of a fixed 512 MiB; they are in the
memory accountant, which keeps them within the common budget together with the
other caches. In the browser each gets half the layer cache's cap.
This commit is contained in:
vangel76 committed 2026-11-19 10:29:54 +01:00
1 parent 6bea5fa6ae
commit 0d9c69563f
10 files changed
+149 -18

No files matched your search

+4 -3
View File
@@ -470,10 +470,11 @@ fn backend(args: &Args, default_demo: bool) -> Result<Backend, Failure> {
Ok(b)
}
/// A wired session; `--gpu` attaches the GPU compositor (renders then follow the project's
/// renderer setting, GPU Acceleration by default).
/// A wired session whose caches share the budget of the installed RAM (#3941); `--gpu` attaches
/// the GPU compositor (renders then follow the project's renderer setting, GPU Acceleration by
/// default).
fn session(args: &Args) -> Result<effectcraft_engine::Session, Failure> {
let mut s = effectcraft_host::session();
let mut s = effectcraft_host::headless_session();
if args.flag("--autosave") {
let dir = effectcraft_host::config_dir().ok_or_else(|| Failure::Error("--autosave: no config directory; set EFFECTCRAFT_CONFIG_DIR".into()))?;
// Read only auto-save settings. Opting in must not change headless rendering or load
+1
View File
@@ -867,6 +867,7 @@ fn save_current_preview(s: &mut Session, p: &Value) -> Result<Value> {
caches: None,
renderer: None,
gpu_frames: s.prefs.memory.gpu_frames(),
cache_budget: Some(s.export_cache_budget()),
};
let r = exporter.export(&job, &mut |_, _| true).map_err(EngineError::Other)?;
s.toast(format!("Saved preview to {}", r.path));
+4
View File
@@ -107,6 +107,8 @@ struct PrerenderCx {
expr: Option<Arc<dyn effectcraft_render::ExprHost>>,
accel: Option<Arc<dyn effectcraft_render::Accelerator>>,
nested_switches: bool,
/// What each of a pre-render's two layer caches may hold (`Session::export_cache_budget`).
cache_budget: usize,
}
/// Render one layer to ProRes 4444 with alpha over its in–out span; `progress` as the exporter's.
@@ -149,6 +151,7 @@ fn prerender(
caches: None,
renderer: None,
gpu_frames: None,
cache_budget: Some(cx.cache_budget),
};
let r = exporter.export(&job, progress)?;
Ok(Prerendered { path: r.path, width: comp.width, height: comp.height, frame_rate: comp.frame_rate, duration: end - start })
@@ -191,6 +194,7 @@ fn export_timeline(s: &mut Session, p: &Value) -> Result<Value> {
expr: s.expr.clone(),
accel: s.accel.clone(),
nested_switches: s.prefs.general.switches_affect_nested_comps,
cache_budget: s.export_cache_budget(),
};
// The pre-renders can take minutes: with `background` (the export dialog) they run as a job
// in Window ▸ Progress instead of with the window waiting (#2269).
+17 -8
View File
@@ -43,21 +43,25 @@ pub struct ExportJob<'a> {
pub renderer: Option<&'a Mutex<Option<effectcraft_render::Backend>>>,
/// Settings ▸ Memory & CPU ▸ GPU Frames Rendered at Once: 1 to 3, `None` for Auto.
pub gpu_frames: Option<usize>,
/// What each of a one-off export's own two layer caches may hold
/// ([`Session::export_cache_budget`], #3941); `None`: the exporter's default.
pub cache_budget: Option<usize>,
}
/// What the jobs of one Render Queue run keep between them (#3335): a layer cache per
/// compositor (a buffer an effect made on the GPU is not the CPU's), together at the budget
/// each job's single cache had before. Both are in the memory accountant's common budget
/// (#3301): they give way with the other caches when it is full.
/// compositor (a buffer an effect made on the GPU is not the CPU's), each with the session's
/// budget for an export's caches ([`Session::export_cache_budget`], #3941). Both are in the
/// memory accountant's common budget (#3301): they give way with the other caches when it is
/// full, so together they never hold more than it.
pub struct RunCaches {
pub gpu: std::sync::Arc<effectcraft_render::LayerCache>,
pub cpu: std::sync::Arc<effectcraft_render::LayerCache>,
}
impl Default for RunCaches {
fn default() -> Self {
let half = effectcraft_render::LayerCache::default().budget() / 2;
let (gpu, cpu) = (std::sync::Arc::new(effectcraft_render::LayerCache::new(half)), std::sync::Arc::new(effectcraft_render::LayerCache::new(half)));
impl RunCaches {
/// The two caches, each with `budget` bytes, registered with the memory accountant.
pub fn new(budget: usize) -> Self {
let (gpu, cpu) = (std::sync::Arc::new(effectcraft_render::LayerCache::new(budget)), std::sync::Arc::new(effectcraft_render::LayerCache::new(budget)));
let accountant = effectcraft_render::memory::Accountant::global();
for cache in [&gpu, &cpu] {
let holder: std::sync::Arc<dyn effectcraft_render::memory::MemoryHolder> = cache.clone();
@@ -257,6 +261,8 @@ struct Work {
nested_switches: bool,
/// Settings ▸ Memory & CPU ▸ GPU Frames Rendered at Once.
gpu_frames: Option<usize>,
/// What each of the run's two layer caches may hold ([`Session::export_cache_budget`]).
cache_budget: usize,
}
/// Where a relative render output goes when there is no default folder and the project is unsaved:
@@ -353,6 +359,7 @@ pub(crate) async fn run_items(
items,
nested_switches: s.prefs.general.switches_affect_nested_comps,
gpu_frames: s.prefs.memory.gpu_frames(),
cache_budget: s.export_cache_budget(),
};
run_work(work, shared, notify).await;
}
@@ -363,7 +370,7 @@ async fn run_work(w: Work, shared: &JobShared, notify: &mut dyn FnMut(&JobShared
let mut s = lock(&shared.state);
s.items_total = w.items.len();
}
let caches = RunCaches::default();
let caches = RunCaches::new(w.cache_budget);
let _run_end = RunEnd(w.accel.as_deref());
for (k, modules) in w.items.iter().enumerate() {
let Some((item, _)) = modules.first() else { continue };
@@ -402,6 +409,7 @@ async fn run_work(w: Work, shared: &JobShared, notify: &mut dyn FnMut(&JobShared
caches: Some(&caches),
renderer: Some(&renderer),
gpu_frames: w.gpu_frames,
cache_budget: Some(w.cache_budget),
};
let rr = w
.exporter
@@ -663,6 +671,7 @@ impl Session {
items,
nested_switches: self.prefs.general.switches_affect_nested_comps,
gpu_frames: self.prefs.memory.gpu_frames(),
cache_budget: self.export_cache_budget(),
};
let shared = Arc::new(JobShared::default());
if wait {
+32
View File
@@ -307,6 +307,38 @@ fn a_queue_run_keeps_its_jobs_warm() {
assert_eq!(ends.0.load(Ordering::SeqCst), 1, "the pool is trimmed once, after the run");
}
#[test]
fn render_queue_runs_and_one_off_exports_follow_the_memory_budget() {
// #3941: a Render Queue run's two layer caches held 512 MiB together and a one-off export's
// 512 MiB each, whatever the memory budget. Both follow the session's budget now.
type Seen = (Option<(usize, usize)>, Option<usize>);
struct Budgets(Mutex<Vec<Seen>>);
impl Exporter for Budgets {
fn formats(&self) -> Vec<OutputFormat> {
OutputFormat::ALL.to_vec()
}
fn export(&self, job: &ExportJob, _: &mut dyn FnMut(u64, u64) -> bool) -> Result<ExportResult, String> {
self.0.lock().unwrap().push((job.caches.map(|c| (c.gpu.budget(), c.cpu.budget())), job.cache_budget));
Ok(ExportResult { path: job.path.to_string(), ..Default::default() })
}
}
let mut s = demo();
let ex = Arc::new(Budgets(Mutex::new(vec![])));
s.exporter = Some(ex.clone());
// A 64 GB machine: 46.4 GB with the default reserve.
s.take_memory_reading(Some(crate::sysinfo::SysMemory { total: 64 << 30, available: 48 << 30 }));
let budget = s.memory_budget().bytes;
assert_eq!(budget as u64, (64 - 6) * (1 << 30) * 80 / 100);
assert_eq!(s.export_cache_budget(), budget, "on the desktop the layer cache's budget is the whole budget");
s.execute("renderQueue.add", json!({"output": crate::tests::stubs::tmp_out("rq/budget.mp4")})).unwrap();
s.execute("renderQueue.render", json!({})).unwrap();
assert_eq!(ex.0.lock().unwrap().last().copied(), Some((Some((budget, budget)), Some(budget))), "a Render Queue run's caches");
s.execute("render.saveCurrentPreview", json!({"path": crate::tests::stubs::tmp_out("rq/budget_preview.mp4")})).unwrap();
assert_eq!(ex.0.lock().unwrap().last().copied(), Some((None, Some(budget))), "a one-off export's own caches");
}
#[test]
fn the_gpu_frames_setting_reaches_every_render_queue_job() {
// #3335: Settings ▸ Memory & CPU ▸ GPU Frames Rendered at Once is Auto (`None`) or 1–3.
@@ -136,6 +136,16 @@ impl Session {
}
}
/// What each of an export's two layer caches (one per compositor) may hold (#3941): the
/// session's layer cache budget. On the desktop that is the whole common budget, and both are
/// in the memory accountant, which keeps them within it together with the session's caches.
/// In the browser each gets half the layer cache's cap, so the two together keep it.
pub fn export_cache_budget(&self) -> usize {
let web = cfg!(target_arch = "wasm32");
let layer = self.memory_budget().caps(web).layer;
if web { layer / 2 } else { layer }
}
/// The memory the caches share for the last memory reading ([`Prefs::memory_budget`]), kept
/// reduced through a low-memory episode until the system has recovered
/// ([`crate::sysinfo::SysMemory::still_low`]), so the budget (and the toast) doesn't flip
+5
View File
@@ -127,6 +127,11 @@ pub struct JobOptions<'a> {
/// a GPU frame measured a frame's working memory. `None`: CPU frames are capped only by
/// `EFFECTCRAFT_CPU_INFLIGHT`.
pub free_memory: Option<&'a (dyn Fn() -> Option<u64> + Sync)>,
/// What each of the job's own two layer caches (one per compositor) may hold when it has no
/// Render Queue run's caches (#3941): the session's budget for an export's caches. Both are
/// in the memory accountant's common budget, so together with the other caches they stay
/// within it. `None`: [`CACHE_BUDGET`].
pub cache_budget: Option<usize>,
}
/// The layer caches of a Render Queue run (see [`JobOptions::caches`]): one per compositor,
+44 -4
View File
@@ -89,8 +89,9 @@ const PROBE_CPU_FRAMES: usize = 8;
/// Jobs shorter than this render on the project's compositor without measuring: the frames
/// the slower one renders for the measurement would cost more than they could save.
const PROBE_MIN_JOB: u64 = 12;
/// Bytes each of a job's two layer caches (one per compositor) may hold: together what the
/// job's single cache held before (`LayerCache::default()`).
/// Bytes each of a job's own two layer caches (one per compositor) may hold when the caller
/// gives no budget ([`crate::JobOptions::cache_budget`]): together what the job's single cache
/// held before (`LayerCache::default()`).
pub const CACHE_BUDGET: usize = 1 << 29;
/// The faster compositor from measured milliseconds per frame (`None`: not measured, or the
@@ -276,7 +277,7 @@ pub(crate) struct Cx<'a> {
/// A job's layer caches: its own, or those of the Render Queue run it belongs to.
enum Caches<'a> {
Own { gpu: Box<LayerCache>, cpu: Box<LayerCache> },
Own { gpu: std::sync::Arc<LayerCache>, cpu: std::sync::Arc<LayerCache> },
Run(crate::JobCaches<'a>),
}
@@ -338,7 +339,17 @@ impl<'a> Cx<'a> {
let frame_times = (job.options.log == RenderLog::PlusPerFrameInfo).then(|| Mutex::new(Vec::new()));
let caches = match job.options.caches {
Some(c) => Caches::Run(c),
None => Caches::Own { gpu: Box::new(LayerCache::new(CACHE_BUDGET)), cpu: Box::new(LayerCache::new(CACHE_BUDGET)) },
None => {
// (in the memory accountant's common budget: they give way with the other caches)
let budget = job.options.cache_budget.unwrap_or(CACHE_BUDGET);
let (gpu, cpu) = (std::sync::Arc::new(LayerCache::new(budget)), std::sync::Arc::new(LayerCache::new(budget)));
let accountant = effectcraft_render::memory::Accountant::global();
for cache in [&gpu, &cpu] {
let holder: std::sync::Arc<dyn effectcraft_render::memory::MemoryHolder> = cache.clone();
accountant.register(&holder);
}
Caches::Own { gpu, cpu }
}
};
// With deferred readbacks, buffers computed from a missed pass's placeholders are not kept.
for r in [crate::JobRenderer::Gpu, crate::JobRenderer::Cpu] {
@@ -1281,6 +1292,35 @@ mod tests {
assert_eq!(Cx::new(&job).gpu_cap(), None, "no accelerator");
}
#[test]
fn a_one_off_exports_caches_take_the_budget_it_is_given() {
// #3941: a one-off export's own caches had 512 MiB each whatever the memory budget; the
// session's budget for an export's caches comes with the job now.
use effectcraft_project::render_queue::{OutputFormat, OutputModule, RenderSettings};
use effectcraft_render::NoFootage;
let (settings, output) = (RenderSettings::default(), OutputModule::for_format(OutputFormat::PngSequence));
let p = Project::default();
for (given, want) in [(None, CACHE_BUDGET), (Some(1500 << 20), 1500 << 20)] {
let job = Job {
project: &p,
footage: &NoFootage,
expr: None,
accel: None,
comp: effectcraft_project::ItemId(0),
settings: &settings,
output: &output,
path: "/c/f_[#####].png",
sink: None,
nested_switches: true,
options: crate::JobOptions { cache_budget: given, ..Default::default() },
};
let cx = Cx::new(&job);
for r in [crate::JobRenderer::Gpu, crate::JobRenderer::Cpu] {
assert_eq!(cx.caches.of(r).budget(), want, "{given:?} {r:?}");
}
}
}
/// A resumed sequence can start with one or two missing frames. Once emitted, their
/// compositor must also be used by every later batch and the item's other output modules.
#[test]
+15 -3
View File
@@ -69,6 +69,7 @@ impl Exporter for FileExporter {
renderer: job.renderer,
gpu_frames: job.gpu_frames,
free_memory: Some(&free_memory),
cache_budget: job.cache_budget,
},
nested_switches: job.nested_switches,
};
@@ -115,14 +116,25 @@ pub fn session() -> Session {
effectcraft_script::install(&mut s);
// The caches' common budget from the start (#3298): the CLI and the MCP server never load
// the settings, and the caches have no limits of their own below it. Without a memory
// reading yet, the budget for unknown RAM.
// reading yet, the budget for unknown RAM ([`headless_session`] takes one).
s.apply_cache_budgets();
// The CLI and the MCP server read no memory: a request for a file's planes over the fixed
// limit asks for it once (#3749).
// A session without a memory reading: a request for a file's planes over the fixed limit
// asks for it once (#3749).
effectcraft_engine::render::memory::set_decode_limit_source(Some(installed_memory_budget));
s
}
/// [`session`] for a frontend without a window (the CLI, its MCP server, scripts and replays):
/// reads the system's memory once (#3941), so the caches share the budget of the installed RAM
/// as in the desktop app instead of the budget for unknown RAM. The desktop app reads it in the
/// background every few seconds instead (`Session::memory_tick`); this waits for the reading
/// (about a second on Windows). A session that can't read it keeps the budget for unknown RAM.
pub fn headless_session() -> Session {
let mut s = session();
s.take_memory_reading(effectcraft_engine::sysinfo::memory());
s
}
/// The memory budget of the installed RAM with the default settings: what one file's decoded
/// planes may take when a request is over the fixed limit and the session read no memory.
fn installed_memory_budget() -> Option<usize> {
+17
View File
@@ -1,9 +1,14 @@
//! #3298: every host session (the desktop app, the CLI, the MCP server) starts with the caches'
//! common budget: the caches have no limits of their own below it, so an unset budget would let
//! them grow until memory runs out.
//!
//! #3941: a headless session (the CLI, its MCP server) reads the system's memory once, so its
//! caches share the budget of the installed RAM, as in the desktop app.
use effectcraft_engine::render::memory::Accountant;
/// One test: the headless session sets the common budget to the installed RAM's, which the
/// first check (the budget for unknown RAM) would see if both ran at once.
#[test]
fn a_host_session_bounds_the_caches() {
let s = effectcraft_host::session();
@@ -11,4 +16,16 @@ fn a_host_session_bounds_the_caches() {
assert!(budget < usize::MAX, "a finite budget");
assert_eq!(budget, s.memory_budget().bytes);
assert!(s.layer_cache.budget() <= budget);
// (a sandbox that can't read the system's memory keeps the budget for unknown RAM)
let Some(memory) = effectcraft_engine::sysinfo::memory() else {
eprintln!("the system's memory can't be read here: the headless reading is not checked");
return;
};
let headless = effectcraft_host::headless_session();
let b = headless.memory_budget();
assert_eq!(b.installed, Some(memory.total), "the budget of the installed RAM, not of unknown RAM");
assert_eq!(b, effectcraft_engine::prefs::Prefs::default().memory_budget(Some(memory), b.reduced));
assert_eq!(headless.layer_cache.budget(), b.bytes, "the caches follow it");
assert_eq!(headless.export_cache_budget(), b.bytes, "exports and Render Queue runs follow it");
}