Evict distant slides and continue preparation when RAM fills

This commit is contained in:
Dandaedre 2026-11-19 18:51:14 +01:00
parent 3000833ac9
commit 2c40e5c1a2
14 changed files with 509 additions and 42 deletions

2
Cargo.lock generated
View File

@ -2212,7 +2212,7 @@ dependencies = [
[[package]]
name = "pdf-presenter"
version = "0.1.18"
version = "0.1.19"
dependencies = [
"bytemuck",
"chrono",

View File

@ -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"

View File

@ -278,6 +278,38 @@ struct Host {
failed_reads: HashSet<std::path::PathBuf>,
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<std::path::PathBuf, Arc<Frame>>,
displayed: Option<&Arc<Frame>>,
state: &HostState,
incoming: usize,
limit: usize,
) -> bool {
loop {
let bytes = cache.values().map(|f| f.rgba.len()).sum::<usize>()
+ 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<Studio>,
host: Option<Host>,
@ -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<Frame> {
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(&current),
&state,
64,
192
));
assert!(!cache.contains_key(&far.info.path));
assert!(cache.contains_key(&current.info.path));
assert!(cache.contains_key(&near.info.path));
cache.remove(&current.info.path);
assert!(!make_output_room(
&mut cache,
Some(&current),
&state,
64,
128
));
assert!(make_output_room(
&mut cache,
Some(&current),
&state,
64,
192
));
}
}

View File

@ -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.),
);
}
});

View File

@ -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<usize>,
@ -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() {

View File

@ -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 {

View File

@ -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());
}

View File

@ -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,

View File

@ -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.

View File

@ -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

View File

@ -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.

View File

@ -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.

View File

@ -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

View File

@ -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