diff --git a/Cargo.lock b/Cargo.lock index a62747b..8c6cf7a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2212,7 +2212,7 @@ dependencies = [ [[package]] name = "pdf-presenter" -version = "0.1.18" +version = "0.1.19" dependencies = [ "bytemuck", "chrono", diff --git a/Cargo.toml b/Cargo.toml index 6f7880b..b4c6d85 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ default-members = ["crates/pdf-presenter"] resolver = "3" [workspace.package] -version = "0.1.18" +version = "0.1.19" edition = "2024" license = "MIT" repository = "https://proxy.dandaedre.com/gitea/idle-org/pdf-presenter" diff --git a/crates/pdf-presenter/src/native.rs b/crates/pdf-presenter/src/native.rs index f4b38c5..cf6aca0 100644 --- a/crates/pdf-presenter/src/native.rs +++ b/crates/pdf-presenter/src/native.rs @@ -278,6 +278,38 @@ struct Host { failed_reads: HashSet, preload_cursor: usize, } +// The last visible frame may outlive its cache entry during a working-set change. +// Count that allocation and pin it until the requested replacement is available. +fn make_output_room( + cache: &mut HashMap>, + displayed: Option<&Arc>, + state: &HostState, + incoming: usize, + limit: usize, +) -> bool { + loop { + let bytes = cache.values().map(|f| f.rgba.len()).sum::() + + displayed + .filter(|f| !cache.contains_key(&f.info.path)) + .map_or(0, |f| f.rgba.len()); + if bytes.saturating_add(incoming) <= limit { + return true; + } + let victim = cache + .iter() + .filter(|(path, _)| { + state.frame.as_ref().is_none_or(|f| &f.path != *path) + && displayed.is_none_or(|f| &f.info.path != *path) + }) + .max_by_key(|(_, f)| f.info.page.abs_diff(state.page)) + .map(|(p, _)| p.clone()); + let Some(victim) = victim else { + return false; + }; + cache.remove(&victim); + } +} + struct App { studio: Option, host: Option, @@ -664,7 +696,7 @@ impl App { host.failed_reads.clear(); host.frame = None; } - // Keep the prepared deck resident; retire previews/superseded resolutions only. + // Mirror the presenter working set, retiring evicted and obsolete frames. let retained: HashSet<_> = state .preload .iter() @@ -694,9 +726,27 @@ impl App { match c.result { Ok(packet) if packet.reply.frame.is_some() => { let info = packet.reply.frame.unwrap(); - let bytes: usize = host.cache.values().map(|f| f.rgba.len()).sum(); + // Ignore completed reads that the presenter has already evicted. + if !host + .state + .preload + .iter() + .chain(host.state.frame.iter()) + .any(|f| f.path == info.path) + { + continue; + } + if host.cache.contains_key(&info.path) { + continue; + } let limit = host.state.buffer_mib.max(256) as usize * 1024 * 1024; - if bytes.saturating_add(packet.data.len()) <= limit { + if make_output_room( + &mut host.cache, + host.frame.as_ref(), + &host.state, + packet.data.len(), + limit, + ) { host.cache.insert( info.path.clone(), Arc::new(Frame { @@ -704,10 +754,9 @@ impl App { rgba: packet.data, }), ); - } else if let Some(path) = reading { - host.failed_reads.insert(path); + } else { let _ = host.acks.try_send(Ack { - status: "Presentation RAM budget reached; increase the budget in Menu to finish buffering.".into(), + status: "Presentation RAM cannot fit active frames; increase the budget.".into(), ..Default::default() }); } @@ -1039,3 +1088,60 @@ pub fn run_output() -> Result<(), Failure> { el.run_app(&mut app)?; Ok(()) } + +#[cfg(test)] +mod buffer_tests { + use super::*; + fn frame(page: usize) -> Arc { + Arc::new(Frame { + info: crate::document::FrameInfo { + page, + width: 4, + height: 4, + path: format!("{page}.rgba").into(), + sha256: String::new(), + }, + rgba: vec![0; 64], + }) + } + #[test] + fn output_evicts_distant_frames_and_counts_pinned_frame_outside_cache() { + let current = frame(1); + let near = frame(2); + let far = frame(20); + let mut cache = [current.clone(), near.clone(), far.clone()] + .into_iter() + .map(|f| (f.info.path.clone(), f)) + .collect(); + let state = HostState { + page: 2, + frame: Some(near.info.clone()), + ..Default::default() + }; + assert!(make_output_room( + &mut cache, + Some(¤t), + &state, + 64, + 192 + )); + assert!(!cache.contains_key(&far.info.path)); + assert!(cache.contains_key(¤t.info.path)); + assert!(cache.contains_key(&near.info.path)); + cache.remove(¤t.info.path); + assert!(!make_output_room( + &mut cache, + Some(¤t), + &state, + 64, + 128 + )); + assert!(make_output_room( + &mut cache, + Some(¤t), + &state, + 64, + 192 + )); + } +} diff --git a/crates/pdf-presenter/src/presenter_ui.rs b/crates/pdf-presenter/src/presenter_ui.rs index 51053ea..8f10f73 100644 --- a/crates/pdf-presenter/src/presenter_ui.rs +++ b/crates/pdf-presenter/src/presenter_ui.rs @@ -444,8 +444,12 @@ pub fn presenter(ui: &mut Ui, s: &mut Studio, native: &mut UiState) { s.output_buffered }; ui.add( - egui::ProgressBar::new(prepared as f32 / (2 * s.count()) as f32) - .desired_height(4.), + egui::ProgressBar::new(if s.evicted_frames > 0 { + s.prepared.len() as f32 / s.count() as f32 + } else { + prepared as f32 / (2 * s.count()) as f32 + }) + .desired_height(4.), ); } }); diff --git a/crates/pdf-presenter/src/studio.rs b/crates/pdf-presenter/src/studio.rs index 9e768f8..0803f32 100644 --- a/crates/pdf-presenter/src/studio.rs +++ b/crates/pdf-presenter/src/studio.rs @@ -53,6 +53,7 @@ pub struct Studio { pub output_buffered: usize, pub ram_blocked: bool, pub cached_slides: usize, + pub evicted_frames: usize, pub loading: bool, pub notes_loading: bool, pub visible_thumbs: HashSet, @@ -139,6 +140,7 @@ impl Studio { output_buffered: 0, ram_blocked: false, cached_slides: 0, + evicted_frames: 0, loading: false, notes_loading: false, visible_thumbs: HashSet::new(), @@ -450,6 +452,7 @@ impl Studio { self.notes_loading = false; self.notes_pending = true; self.cached_slides = 0; + self.evicted_frames = 0; self.generation += 1; self.frames.clear(); self.prepared.clear(); @@ -562,14 +565,14 @@ impl Studio { && self.prepared.len() < self.count() && let Some(page) = (0..self.count()).rev().find(|p| { let key = (*p, self.target_edge); - !self.frames.contains_key(&key) + !self.prepared.contains(p) && !self.failed.contains(&key) && Some(key) != self.bg_job }) { self.schedule(page, self.target_edge, true); } - if !self.bg_busy && self.prepared.len() < self.count() { + if !self.bg_busy { let mut jobs = vec![]; for page in [self.requested + 1, self.requested.saturating_sub(1)] { if page < self.count() { @@ -577,7 +580,20 @@ impl Studio { } } // Prepare the entire show, not just the currently visible neighbourhood. - jobs.extend((0..self.count()).map(|p| (p, self.target_edge))); + if self.prepared.len() < self.count() { + jobs.retain(|(p, _)| !self.prepared.contains(p)); + jobs.extend( + (0..self.count()) + .filter(|p| !self.prepared.contains(p)) + .map(|p| (p, self.target_edge)), + ); + } else { + if self.browser_open { + jobs.extend(self.visible_thumbs.iter().map(|p| (*p, self.target_edge))); + } + // Refill available RAM after navigation or a budget increase. + jobs.extend((0..self.count()).map(|p| (p, self.target_edge))); + } if let Some((page, edge)) = jobs.into_iter().find(|key| { !self.frames.contains_key(key) && Some(*key) != self.fg_job @@ -588,9 +604,7 @@ impl Studio { } } } - if self.prepared.len() == self.count() { - self.ram_blocked = false; - } + let edge = self .monitors .iter() @@ -615,19 +629,39 @@ impl Studio { self.frames.retain(|(_, e), _| *e == edge || *e == 512); self.preparation_started = Instant::now(); self.cached_slides = 0; + self.evicted_frames = 0; self.output_buffered = 0; self.ram_blocked = false; self.new_output = true; } } fn schedule(&mut self, page: usize, edge: u32, foreground: bool) { - // Reserve the worst-case square frame plus the other in-flight render. + // Reserve both worker slots before admission, including progressive previews. let reserve = 2 * edge as usize * edge as usize * 4; - self.ram_blocked = self.buffer_bytes().saturating_add(reserve) - > self.settings.buffer_mib as usize * 1024 * 1024; - if self.ram_blocked { - return; + let limit = self.settings.buffer_mib as usize * 1024 * 1024; + while self.buffer_bytes().saturating_add(reserve) > limit { + let victim = self + .frames + .keys() + .copied() + .filter(|(p, _)| { + *p != self.requested && Some(*p) != self.displayed && *p != page + // Once processed, speculative prefetch must improve locality rather + // than continually swap two equally distant cached slides. + && (!self.prepared.contains(&page) + || page == self.requested + || p.abs_diff(self.requested) > page.abs_diff(self.requested)) + }) + .max_by_key(|(p, e)| (*e != self.target_edge, p.abs_diff(self.requested), *p)); + let Some(victim) = victim else { + self.ram_blocked = true; + return; + }; + self.frames.remove(&victim); + self.evicted_frames += 1; + self.new_output = true; } + self.ram_blocked = false; let request = Request::Render { epoch: self.generation, path: self.deck.as_ref().unwrap().path.clone(), @@ -668,6 +702,26 @@ impl Studio { self.pending_save = true; } pub fn remember_buffer_budget(&mut self) { + let reserved: usize = self + .fg_job + .iter() + .chain(self.bg_job.iter()) + .map(|(_, edge)| *edge as usize * *edge as usize * 4) + .sum(); + let limit = (self.settings.buffer_mib as usize * 1024 * 1024).saturating_sub(reserved); + while self.buffer_bytes() > limit { + let victim = self + .frames + .keys() + .copied() + .filter(|(p, _)| *p != self.requested && Some(*p) != self.displayed) + .max_by_key(|(p, _)| p.abs_diff(self.requested)); + let Some(victim) = victim else { + break; + }; + self.frames.remove(&victim); + self.evicted_frames += 1; + } self.pending_save = true; self.ram_blocked = false; self.new_output = true; @@ -675,10 +729,47 @@ impl Studio { pub fn buffer_bytes(&self) -> usize { self.frames.values().map(|f| f.rgba.len()).sum() } + pub fn resident_slides(&self) -> usize { + self.frames + .keys() + .filter(|(_, edge)| *edge == self.target_edge) + .count() + } + fn rolling_status(&self, french: bool) -> String { + let processed = self.prepared.len(); + let total = self.count(); + let eta = if processed > 0 && processed < total { + format!( + " · ETA ~{} s", + (self.preparation_started.elapsed().as_secs_f64() / processed as f64 + * (total - processed) as f64) + .ceil() as u64 + ) + } else { + String::new() + }; + if french { + format!( + "Cache tournant — {processed}/{total} préparées · {}/{} en RAM ({} Mio) · {} libérées · rechargement du cache à la demande{eta}", + self.resident_slides(), + total, + self.buffer_bytes() / (1024 * 1024), + self.evicted_frames + ) + } else { + format!( + "Rolling buffer — {processed}/{total} prepared · {}/{} in RAM ({} MiB) · {} evicted · cached slides reload on demand{eta}", + self.resident_slides(), + total, + self.buffer_bytes() / (1024 * 1024), + self.evicted_frames + ) + } + } pub fn fully_buffered(&self) -> bool { !self.loading && self.count() > 0 - && self.prepared.len() == self.count() + && self.resident_slides() == self.count() && (self.routes.presentation.is_empty() || self.output_buffered == self.count()) } fn preparation_status_fr(&self) -> String { @@ -700,9 +791,12 @@ impl Studio { self.target_edge ); } + if self.evicted_frames > 0 { + return self.rolling_status(self.settings.language.french()); + } if self.ram_blocked { return format!( - "Budget RAM atteint — {n}/{total} en mémoire. Augmentez le budget dans Menu pour terminer." + "Budget RAM atteint — {n}/{total} en mémoire. Mémoire insuffisante pour les images actives et les rendus en cours." ); } if !self.failed.is_empty() { @@ -757,9 +851,12 @@ impl Studio { self.target_edge ); } + if self.evicted_frames > 0 { + return self.rolling_status(self.settings.language.french()); + } if self.ram_blocked { return format!( - "RAM budget reached — {n}/{total} buffered. Increase the buffer in Menu; the show is not fully loaded." + "RAM budget reached — {n}/{total} buffered. Cannot fit active frames and render reservations; increase the budget." ); } if !self.failed.is_empty() { diff --git a/crates/pdf-presenter/tests/native.rs b/crates/pdf-presenter/tests/native.rs index c66a414..f31e015 100644 --- a/crates/pdf-presenter/tests/native.rs +++ b/crates/pdf-presenter/tests/native.rs @@ -155,6 +155,36 @@ fn independent_output_acknowledges_frames_and_blanking() { break; } } + // Rolling-buffer updates evict absent entries, then reload them from processed + // files when they re-enter the working set, without marking them as failed. + for (sequence, count, page) in [(90, 2, 0), (91, 8, 7)] { + write_json( + &mut input, + &HostState { + sequence, + page, + generation: 99, + frame: Some(frames[page].info.clone()), + preload: frames[..count].iter().map(|f| f.info.clone()).collect(), + buffer_mib: 256, + monitors: vec![monitor.clone()], + fullscreen: false, + blanked: false, + ..Default::default() + }, + ) + .unwrap(); + let deadline = Instant::now() + Duration::from_secs(10); + loop { + let ack = rx + .recv_timeout(deadline.saturating_duration_since(Instant::now())) + .expect("output working-set reload deadline"); + assert!(ack.status.is_empty(), "{}", ack.status); + if ack.sequence == sequence && ack.buffered == count && ack.page == Some(page) { + break; + } + } + } // The independent output must navigate entirely from RAM after preparation. std::fs::remove_dir_all(temp.path().join("cache")).unwrap(); for page in 0..8 { diff --git a/crates/pdf-presenter/tests/preparation.rs b/crates/pdf-presenter/tests/preparation.rs index 39fcda5..69ab47b 100644 --- a/crates/pdf-presenter/tests/preparation.rs +++ b/crates/pdf-presenter/tests/preparation.rs @@ -128,7 +128,7 @@ fn changing_screen_resolution_reprepares_and_readiness_waits_for_output() { } #[test] -fn preparation_pauses_at_ram_budget_and_resumes_without_evicting_ready_slides() { +fn impossibly_small_budget_reports_pressure_and_recovers() { let temp = tempfile::tempdir().unwrap(); let pdf = temp.path().join("show.pdf"); common::pdf(&pdf); @@ -190,3 +190,156 @@ fn opening_document_honors_auto_show_and_navigation_preserves_manual_blank() { assert!(s.blanked); } } + +#[test] +fn rolling_buffer_finishes_processing_and_reloads_evicted_slides_without_churn() { + let temp = tempfile::tempdir().unwrap(); + let dir = temp.path().join("slides"); + std::fs::create_dir(&dir).unwrap(); + for i in 0..16 { + common::image(&dir.join(format!("slide{i}.png")), [i * 10, 128, 200, 255]); + } + let cache = temp.path().join("processed"); + let mut s = studio(&dir, &cache); + s.settings.buffer_mib = 6; + let deadline = Instant::now() + Duration::from_secs(20); + while s.count() == 0 || s.prepared.len() < s.count() { + s.poll(); + assert!(s.buffer_bytes() <= 6 * 1024 * 1024); + assert!( + Instant::now() < deadline, + "{} / {}", + s.preparation_status(), + s.status + ); + std::thread::sleep(Duration::from_millis(2)); + } + assert!(s.evicted_frames > 0); + assert!(s.resident_slides() < s.count()); + assert!(!s.fully_buffered()); + assert!(s.preparation_status().contains("Rolling buffer")); + let timestamps: Vec<_> = artifacts(&cache) + .iter() + .filter(|p| p.file_name().unwrap().to_str().unwrap().contains("-640-")) + .map(|p| (p.clone(), std::fs::metadata(p).unwrap().modified().unwrap())) + .collect(); + assert_eq!(timestamps.len(), 16); + let missing = (0..s.count()) + .find(|p| !s.frames.contains_key(&(*p, 640))) + .unwrap(); + for page in [missing, 15, 0, 8, 2] { + s.displayed = Some(s.requested); + s.execute(Action::Go(page)); + let deadline = Instant::now() + Duration::from_secs(5); + while !s.frames.contains_key(&(page, 640)) { + s.poll(); + assert!(s.buffer_bytes() <= 6 * 1024 * 1024); + assert!( + Instant::now() < deadline, + "{} / {}", + s.preparation_status(), + s.status + ); + std::thread::sleep(Duration::from_millis(2)); + } + assert_eq!(s.full_frame(page).unwrap().info.page, page); + s.displayed = Some(page); + } + // Let neighbour prefetch settle, then ensure idle polls do not cycle evictions. + for _ in 0..100 { + s.poll(); + std::thread::sleep(Duration::from_millis(2)); + } + let evictions = s.evicted_frames; + for _ in 0..100 { + s.poll(); + std::thread::sleep(Duration::from_millis(2)); + } + assert_eq!(s.evicted_frames, evictions); + for (path, timestamp) in timestamps { + assert_eq!( + std::fs::metadata(path).unwrap().modified().unwrap(), + timestamp + ); + } + s.settings.buffer_mib = 256; + s.remember_buffer_budget(); + prepare(&mut s); + s.settings.buffer_mib = 6; + s.remember_buffer_budget(); + assert!(s.buffer_bytes() <= 6 * 1024 * 1024); + assert!(s.full_frame(s.requested).is_some()); + assert!(!s.fully_buffered()); +} + +#[test] +#[ignore = "manual stress test: set PDF_PRESENTER_STRESS_PDF to an authorized local PDF"] +fn real_pdf_exceeds_budget_and_keeps_navigating() { + let path = PathBuf::from( + std::env::var_os("PDF_PRESENTER_STRESS_PDF").expect("PDF_PRESENTER_STRESS_PDF"), + ); + let temp = tempfile::tempdir().unwrap(); + let mut s = studio(&path, &temp.path().join("cache")); + s.monitors[0].size = (1920, 1080); + s.settings.buffer_mib = 256; + let deadline = Instant::now() + Duration::from_secs(180); + let mut peak = 0; + while s.evicted_frames < 10 { + s.poll(); + peak = peak.max(s.buffer_bytes()); + assert!(peak <= 256 * 1024 * 1024); + assert!( + Instant::now() < deadline, + "{} / {}", + s.preparation_status(), + s.status + ); + std::thread::sleep(Duration::from_millis(5)); + } + eprintln!( + "Pressure reached: {} · peak {} MiB", + s.preparation_status(), + peak / (1024 * 1024) + ); + assert!(s.full_frame(0).is_some()); + assert!(!s.fully_buffered()); + let missing = (0..s.count()) + .find(|p| s.prepared.contains(p) && !s.frames.contains_key(&(*p, s.target_edge))) + .unwrap(); + for page in [missing, s.count() / 2, s.count() - 1, 0] { + let start = Instant::now(); + s.displayed = Some(s.requested); + s.execute(Action::Go(page)); + while !s.frames.contains_key(&(page, s.target_edge)) { + s.poll(); + assert!(s.buffer_bytes() <= 256 * 1024 * 1024); + assert!( + start.elapsed() < Duration::from_secs(35), + "{} / {}", + s.preparation_status(), + s.status + ); + std::thread::sleep(Duration::from_millis(5)); + } + s.displayed = Some(page); + eprintln!( + "Slide {} available in {:?}; {}", + page + 1, + start.elapsed(), + s.preparation_status() + ); + } + while s.prepared.len() < s.count() { + s.poll(); + assert!(s.buffer_bytes() <= 256 * 1024 * 1024); + assert!( + Instant::now() < deadline, + "{} / {}", + s.preparation_status(), + s.status + ); + std::thread::sleep(Duration::from_millis(5)); + } + eprintln!("Whole PDF processed: {}", s.preparation_status()); + assert!(!s.fully_buffered()); +} diff --git a/docs/changelog.md b/docs/changelog.md index 5df4512..fbfc935 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -2,6 +2,17 @@ ## Unreleased +### 0.1.19 + +- Continue preparing oversized decks by evicting distant frames, protecting active + slides and retaining processed disk artifacts. Reload evicted slides on demand. +- Mirror the rolling working set in the output process; account for its pinned + last frame, discard obsolete reads and free distant frames before replacement. +- Report prepared versus RAM-resident counts, evictions and ETA; reserve READY + for fully resident decks. Avoid idle eviction loops and refill when budget grows. +- Regression-test pressure, cached reload, idle stability and budget changes; + exercise the authorized 322-page Ravenous.pdf with a 256 MiB decoded budget. + ### 0.1.18 - Use uv-selected Python 3.11+ throughout Jenkins, including badge initialization, diff --git a/docs/development/native-implementation.md b/docs/development/native-implementation.md index e30abe8..40f8452 100644 --- a/docs/development/native-implementation.md +++ b/docs/development/native-implementation.md @@ -191,3 +191,45 @@ Formatting, warnings-denied Clippy/rustdoc and macOS aarch64 compilation pass. Whole-application coverage is 83.97%, with no production exclusions. Linux and Windows x86_64 release builds succeed. Runtime retesting on Windows remains necessary for the reported platform behavior. + + +## 0.1.19 bounded rolling buffers + +Supersedes 0.1.13's memory-pressure pause: preparation now evicts distant non-active +frames while retaining processed disk artifacts. Processed-slide progress and RAM +residency are distinct; foreground navigation reloads cached slides through workers. +The displayed/requested pages remain protected, the output mirrors the working set, +and old reads cannot repopulate frames the presenter has already evicted. Output +admission accounts for a last-visible frame held outside its cache. Once preparation +finishes, speculative reloads must improve locality to avoid endless eviction cycles. +Budget increases refill RAM; decreases free non-active frames with in-flight capacity +reserved. Full-deck READY semantics are preserved, while rolling mode explicitly +reports disk reloads, actual resident count, evictions and preparation ETA. + +Validation: 49 automated Rust tests, 12 Python tests, formatting and warnings-denied +Clippy/rustdoc pass; whole-app line coverage is 84.34%. New tests cover eviction, +cached reload without artifact rewrites, idle stability, budget reduction/refill, +and pinned output allocations. Native X11 output tests shrink the working set, reload +evicted entries, then delete processed files and verify the refilled buffer can still +navigate entirely from RAM. macOS aarch64 compile-check passes. + +The user-authorized local `test_pdf/Ravenous.pdf` (322 pages, 60661865 bytes) was tested +at a 1920-pixel target edge and 256 MiB decoded budget using the release worker. +All 322 pages were processed; the final working set held 22 slides/about 218 MiB, +with 303 evictions. The test asserted the decoded budget throughout processing and +navigation. An evicted slide, middle, final and first page all became available; +observed request-to-presenter-frame times were 326–362 ms under concurrent background +preparation. The complete stress test took 12.29 seconds. These are worker/state +measurements, not optical audience latency or total process RSS. Worker/UI/texture +memory remains additional. The source SHA-256 was unchanged after the test. + +Reproduce explicitly with an authorized local deck (never a CI/private fixture upload): + +```sh +PDF_PRESENTER_STRESS_PDF=/path/to/Ravenous.pdf cargo test --locked --release \ + --test preparation real_pdf_exceeds_budget_and_keeps_navigating -- --ignored --nocapture +``` + +Linux and Windows x86_64 release builds both succeed. +The test uses temporary processed files and cleans them up. Real Windows/macOS +multiscreen/runtime acceptance remains separate from these regression checks. diff --git a/docs/development/tasks.md b/docs/development/tasks.md index a55e890..e3c474e 100644 --- a/docs/development/tasks.md +++ b/docs/development/tasks.md @@ -20,6 +20,10 @@ two workers, screen-derived resolution, cache-first opening, retained complete b explicit preparation progress/ETA and memory-pressure pause. T01's full optical latency matrix and T15's persistent disk quota remain open. +0.1.19 replaces the memory-pressure pause with bounded rolling eviction, while +retaining full RAM residency when the deck fits. Processed-page progress is separate +from current residency; cached slides reload through workers after eviction. + ## P0 — Instrumentation and two-display proof - [ ] T01: Add monotonic startup/input/frame markers, bounded logs and a benchmark diff --git a/docs/interfaces/extraction-cache.md b/docs/interfaces/extraction-cache.md index 5270b08..68b9166 100644 --- a/docs/interfaces/extraction-cache.md +++ b/docs/interfaces/extraction-cache.md @@ -32,11 +32,21 @@ Smaller screens share the largest variant. An exact verified target-size cache h bypasses preview rendering. Resolution changes use a distinct existing/new artifact key. The disk schema remains v1; prior artifacts at matching resolutions remain usable. -The entire decoded deck is retained in presenter and presentation-process RAM. -`buffer_mib` (default 1024 per process) bounds each decoded cache; render reservations -prevent overfilling the presenter budget. No eviction-based false READY state is -allowed. Insufficient capacity pauses preparation until the budget increases. -Only temporary preview/superseded-resolution frames are retired. Source/artifact -reads happen during preparation/recovery, not prepared navigation. OS paging and -software composition are outside this application-level no-file-read guarantee. +When the deck fits, the entire decoded deck is retained in presenter and output RAM. +As of 0.1.19, reaching `buffer_mib` evicts distant non-active frames and continues +processing the rest of the deck. Requested/displayed slides are protected; foreground +navigation takes priority. Render reservations still bound presenter admissions. +Processed-slide progress is independent of RAM residency: an evicted slide remains +prepared on disk and reloads through a worker on demand. Once all slides are processed, +background prefetch improves locality without endlessly exchanging distant slides. +Increasing the budget refills RAM; lowering it retires non-active frames immediately, +allowing for in-flight reservations. A budget too small for protected frames and render +reservations still reports pressure rather than discarding active content. + +The output host mirrors the presenter working set, counts its last displayed frame +if retained outside the cache, and frees distant entries before admitting replacements. +Stale reads for evicted entries are discarded. READY requires the whole deck to be +resident in both processes; rolling-buffer mode explicitly permits background disk +reads and is never described as fully RAM-buffered. OS paging and software composition +are outside this application-level no-file-read guarantee. The disk schema remains v1. Disk eviction/quota remains outstanding; full disk reports an explicit error. diff --git a/docs/interfaces/process-protocol.md b/docs/interfaces/process-protocol.md index c96721d..5e7f335 100644 --- a/docs/interfaces/process-protocol.md +++ b/docs/interfaces/process-protocol.md @@ -35,9 +35,11 @@ status. The two workers prepare the remaining deck concurrently with foreground navigation able to supersede outstanding work. HostState now carries a document/resolution generation, decoded RAM budget and the -complete available target-frame preload list. The host retains the whole prepared -deck, acknowledges the number buffered for that generation, and retires only temporary -previews or obsolete generations/resolutions. READY requires both presenter and host +currently resident target-frame preload list. Since 0.1.19 the host mirrors this +working set, retires evicted entries and discards stale read completions. It can +free distant cached frames to admit a replacement while protecting the displayed +and requested frames. Its acknowledgment counts actual resident entries for that +generation, rather than all previously processed slides. READY requires both presenter and host counts to reach the deck total. Stale acknowledgments cannot mark another resolution ready. The bounded JSON envelope and raw-frame limits remain unchanged. This protocol still requires the same executable build at both ends. diff --git a/docs/interfaces/settings.md b/docs/interfaces/settings.md index a93d37e..82c7032 100644 --- a/docs/interfaces/settings.md +++ b/docs/interfaces/settings.md @@ -40,7 +40,8 @@ flushed temporary file. Unknown fields are ignored and not preserved on round tr - `buffer_mib`: integer 256–16384, default 1024, added in 0.1.13. Decoded slide RAM allowance for each presenter/output process; one MiB = 1048576 bytes. Additional worker/texture/UI memory is not included. Older v1 files default to 1024. The menu - persists changes asynchronously; lowering does not evict resident frames. + persists changes asynchronously. Since 0.1.19, lowering evicts non-active frames + while reserving room for outstanding renders; increasing allows RAM refill. Transient reveals, blank/current/selected slides, elapsed time, loaded document, Change on click and worker state are not persisted. HTML prototype localStorage is diff --git a/docs/user-guide.md b/docs/user-guide.md index c2a75bc..f3c1f8e 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -99,16 +99,23 @@ explicit status. ETAs use observed throughput and may change on complex slides. outputs are assigned, acknowledged in the independent presentation host's RAM. Navigation then performs no application slide-file reads, PDF rendering or image decoding. Raster composition still happens, and the OS can page memory under pressure. -The entire prepared deck stays resident instead of evicting distant slides. +The entire deck stays resident when it fits the configured RAM budget. Menu → Preferences → RAM budget controls the decoded-slide allowance for **each process**, default 1024 MiB, configurable from 256 to 16384 MiB. Presenter and output can each consume that allowance; textures, workers and other application memory are additional. -Preparation reserves capacity for in-flight frames. If the deck cannot fit, it pauses -and reports that it is **not fully loaded**, rather than claiming READY and loading -slides later. Increase the budget within available physical RAM to resume. Lowering -the budget does not evict already buffered slides; reopen to apply a lower allocation -to an existing show. Cold rendering/decoding may continue while you present early. +Preparation reserves capacity for in-flight frames. When the deck cannot fit, the +**Rolling buffer** frees distant slides and continues preparing the remaining pages. +The requested slide and last acknowledged output remain protected. The status shows +prepared pages, actual RAM-resident pages, evictions and preparation ETA. Evicted +slides keep their processed files and reload in the background when requested; +this mode can require disk access and does not claim READY or zero-load navigation. +The last output frame stays visible until its replacement is available. + +Increasing the budget lets the app refill the buffer; reducing it frees non-active +frames while preserving room for outstanding renders. If even the active frames and +render reservations cannot fit, the app reports that specific pressure. Cold rendering +and cache preparation can continue while you present early. After a host restart or resolution change, wait for READY again for RAM-only playback. ## Recovery and portability