Add disk cache size and lifetime limits with manual expunge

This commit is contained in:
Dandaedre 2026-11-20 11:36:39 +01:00
parent b4e4429290
commit ae0ff93a8a
20 changed files with 603 additions and 7 deletions

2
Cargo.lock generated
View File

@ -2245,7 +2245,7 @@ dependencies = [
[[package]]
name = "pdf-presenter"
version = "0.1.69"
version = "0.1.70"
dependencies = [
"bytemuck",
"chrono",

View File

@ -4,7 +4,7 @@ default-members = ["crates/pdf-presenter"]
resolver = "3"
[workspace.package]
version = "0.1.69"
version = "0.1.70"
edition = "2024"
license = "MIT"
repository = "https://proxy.dandaedre.com/gitea/idle-org/pdf-presenter"

View File

@ -0,0 +1,209 @@
//! Bounded worker-only maintenance of disposable rendered slide files.
use serde::{Deserialize, Serialize};
use std::{
fs::{self, File, OpenOptions},
path::{Path, PathBuf},
time::{Duration, SystemTime},
};
#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(default)]
pub struct Policy {
pub max_mib: u32,
pub max_days: u32,
}
impl Default for Policy {
fn default() -> Self {
Self {
max_mib: 10240,
max_days: 30,
}
}
}
impl Policy {
pub fn validate(&self) -> Result<(), String> {
if !(64..=1048576).contains(&self.max_mib) || !(1..=3650).contains(&self.max_days) {
return Err("Disk cache must be 64–1048576 MiB and 1–3650 days".into());
}
Ok(())
}
}
#[derive(Default, Serialize, Deserialize)]
pub struct Report {
pub removed_bytes: u64,
pub remaining_bytes: u64,
pub removed_files: usize,
pub skipped_files: usize,
}
fn lock_file(project: &Path) -> Result<File, String> {
let path = project.join(".lease-v1");
if fs::symlink_metadata(&path).is_ok_and(|m| !m.is_file()) {
return Err("Invalid cache lease file".into());
}
OpenOptions::new()
.read(true)
.write(true)
.create(true)
.truncate(false)
.open(path)
.map_err(|e| e.to_string())
}
/// Scoped OS lock, explicitly unlocked before close so a concurrent fork cannot
/// accidentally prolong ownership until the child execs.
pub struct Lease(File);
impl Drop for Lease {
fn drop(&mut self) {
let _ = self.0.unlock();
}
}
/// A live document holds a shared OS lock; process exit releases it automatically.
pub fn lease(cache: &Path, key: &str) -> Result<Lease, String> {
let project = cache.join(key);
fs::create_dir_all(&project).map_err(|e| e.to_string())?;
let file = lock_file(&project)?;
// Only a killable worker waits here, never an input/event loop.
file.lock_shared().map_err(|e| e.to_string())?;
Ok(Lease(file))
}
fn hash_name(path: &Path) -> bool {
path.file_name()
.and_then(|s| s.to_str())
.is_some_and(|s| s.len() == 64 && s.bytes().all(|b| b.is_ascii_hexdigit()))
}
fn artifact(path: &Path) -> bool {
let Some(name) = path.file_name().and_then(|s| s.to_str()) else {
return false;
};
let Some((page, rest)) = name.split_once('-') else {
return false;
};
let Some((edge, suffix)) = rest.split_once('-') else {
return false;
};
page.parse::<usize>().is_ok()
&& edge.parse::<u32>().is_ok()
&& matches!(
suffix,
"hayro09.rgba" | "hayro09-straight.rgba" | "extraction.json"
)
}
struct Entry {
path: PathBuf,
project: PathBuf,
bytes: u64,
modified: SystemTime,
}
/// Expire by artifact modification time, then evict oldest first to the byte target.
/// Manual expunge removes all eligible artifacts. Active projects are always retained.
pub fn clean(
root: &Path,
policy: &Policy,
protected: &[String],
manual: bool,
now: SystemTime,
) -> Result<Report, String> {
policy.validate()?;
match fs::symlink_metadata(root) {
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Report::default()),
Ok(m) if m.is_dir() => (),
_ => return Err("Cache root is not a regular directory".into()),
}
let mut entries = Vec::new();
let mut report = Report::default();
let mut visited = 0usize;
// Fixed depth and entry ceiling bound memory, including unexpected entries.
let mut scan = vec![(root.to_owned(), 0)];
while let Some((dir, depth)) = scan.pop() {
for item in fs::read_dir(&dir).map_err(|e| e.to_string())? {
visited += 1;
if visited > 200_000 {
return Err("Cache scan exceeds 200000 entries; cleanup stopped".into());
}
let item = item.map_err(|e| e.to_string())?;
let kind = item.file_type().map_err(|e| e.to_string())?;
let path = item.path();
if depth < 2 && kind.is_dir() && hash_name(&path) {
scan.push((path, depth + 1));
} else if depth == 2 && kind.is_file() {
let meta = item.metadata().map_err(|e| e.to_string())?;
report.remaining_bytes = report.remaining_bytes.saturating_add(meta.len());
if artifact(&path) {
entries.push(Entry {
path,
project: dir.parent().unwrap().to_owned(),
bytes: meta.len(),
modified: meta.modified().map_err(|e| e.to_string())?,
});
}
}
}
}
entries.sort_by(|a, b| {
a.modified
.cmp(&b.modified)
.then_with(|| a.path.cmp(&b.path))
});
let max_bytes = u64::from(policy.max_mib) * 1024 * 1024;
let lifetime = Duration::from_secs(u64::from(policy.max_days) * 86400);
for entry in entries {
if !manual
&& report.remaining_bytes <= max_bytes
&& now.duration_since(entry.modified).unwrap_or_default() < lifetime
{
continue;
}
let key = entry.project.file_name().unwrap().to_string_lossy();
if protected.iter().any(|p| p == &key) {
report.skipped_files += 1;
continue;
}
let lock = lock_file(&entry.project)?;
match lock.try_lock() {
Ok(()) => (),
Err(std::fs::TryLockError::WouldBlock) => {
report.skipped_files += 1;
continue;
}
Err(e) => return Err(e.to_string()),
}
let _lease = Lease(lock);
// Recheck after obtaining the lock: a worker may have replaced this artifact.
let meta = match fs::symlink_metadata(&entry.path) {
Ok(m) => m,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
Err(e) => return Err(e.to_string()),
};
if !meta.is_file()
|| meta.len() != entry.bytes
|| meta.modified().ok() != Some(entry.modified)
{
report.skipped_files += 1;
continue;
}
fs::remove_file(&entry.path).map_err(|e| e.to_string())?;
report.removed_bytes += entry.bytes;
report.remaining_bytes = report.remaining_bytes.saturating_sub(entry.bytes);
report.removed_files += 1;
// Never remove project/lease files: unlinking a lock could split ownership.
let _ = fs::remove_dir(entry.path.parent().unwrap());
}
Ok(report)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn scoped_release_is_not_prolonged_by_a_duplicated_descriptor() {
let temp = tempfile::tempdir().unwrap();
let key = format!("{:064x}", 1);
let lease = lease(temp.path(), &key).unwrap();
let inherited = lease.0.try_clone().unwrap();
drop(lease);
let exclusive = lock_file(&temp.path().join(key)).unwrap();
exclusive.try_lock().unwrap();
drop(Lease(exclusive));
drop(inherited);
}
}

View File

@ -43,6 +43,7 @@ pub struct Document {
pub info: DeckInfo,
source: Source,
cache: PathBuf,
_cache_lease: crate::cache::Lease,
}
enum Source {
Pdf(Pdf),
@ -120,6 +121,7 @@ impl Document {
fn open_inner(path: &Path, cache: PathBuf, load_notes: bool) -> Result<Self, String> {
let path = std::fs::canonicalize(path).map_err(|e| e.to_string())?;
let key = settings::project_key(&path);
let cache_lease = crate::cache::lease(&cache, &key)?;
let mut warnings = vec![];
let mut notes = vec![];
let names;
@ -265,6 +267,7 @@ impl Document {
info,
source,
cache,
_cache_lease: cache_lease,
})
}
pub fn render(&self, page: usize, edge: u32) -> Result<Frame, String> {

View File

@ -95,3 +95,6 @@ pub mod tools;
pub mod notes;
pub mod zoom;
/// Disk cache retention and worker-only cleanup.
pub mod cache;

View File

@ -39,6 +39,13 @@ pub fn tr<'a>(ctx: &egui::Context, text: &'a str) -> &'a str {
return text;
}
match text {
"Disk cache" => "Cache disque",
"Maximum total size (MiB)" => "Taille totale maximale (Mio)",
"Expire after (days since rendering)" => "Expiration (jours depuis le rendu)",
"Oldest files are removed first. Active decks are protected and may exceed the limit. Cleanup runs every minute." => {
"Les fichiers les plus anciens sont supprimés en premier. Les présentations actives sont protégées et peuvent dépasser la limite. Nettoyage toutes les minutes."
}
"Expunge unused cache now" => "Purger le cache inutilisé maintenant",
"Keep fitted page area when zooming" => {
"Conserver la zone ajustée de la page pendant le zoom"
}

View File

@ -2340,6 +2340,17 @@ fn menu(ui: &mut Ui, s: &mut Studio) {
if ui.add(egui::Slider::new(&mut s.settings.buffer_mib,64..=16384).text("MiB")).changed() {s.remember_buffer_budget();}
ui.small(tr(&locale,"Raise only within available RAM; OS paging can cause delays. Screen rendering is capped at 4096 px."));
ui.separator();
ui.collapsing(tr(&locale, "Disk cache"), |ui| {
let mut changed = false;
ui.label(tr(&locale, "Maximum total size (MiB)"));
changed |= ui.add(egui::DragValue::new(&mut s.settings.disk_cache.max_mib).range(64..=1048576).speed(64)).changed();
ui.label(tr(&locale, "Expire after (days since rendering)"));
changed |= ui.add(egui::DragValue::new(&mut s.settings.disk_cache.max_days).range(1..=3650)).changed();
if changed { s.remember_cache_policy(); }
ui.small(tr(&locale, "Oldest files are removed first. Active decks are protected and may exceed the limit. Cleanup runs every minute."));
if ui.add_enabled(!s.cache_busy && !s.loading && s.initialized, egui::Button::new(tr(&locale, "Expunge unused cache now"))).clicked() { s.clean_cache(true); }
ui.small(&s.cache_status);
});
ui.label(s.preparation_status());
ui.collapsing(tr(&locale,"Storage locations"), |ui| {
ui.label(format!("{}: {}",if s.settings.language.french(){"Diapositives préparées"}else{"Processed slides"},s.cache_path.display()));

View File

@ -224,6 +224,7 @@ pub struct Settings {
pub browser_monitor: Option<String>,
pub thumbnail_size: f32,
pub buffer_mib: u32,
pub disk_cache: crate::cache::Policy,
pub auto_show: bool,
pub zoom_enabled: bool,
pub zoom_keep_fitted_area: bool,
@ -267,6 +268,7 @@ impl Default for Settings {
browser_monitor: None,
thumbnail_size: 220.,
buffer_mib: default_buffer_mib(),
disk_cache: Default::default(),
auto_show: true,
zoom_enabled: false,
zoom_keep_fitted_area: false,
@ -280,6 +282,7 @@ impl Settings {
if self.version != 1 {
return Err(format!("Unsupported settings version {}", self.version));
}
self.disk_cache.validate()?;
if !(64..=16384).contains(&self.buffer_mib) {
return Err("RAM buffer must be 64–16384 MiB per process".into());
}

View File

@ -117,6 +117,10 @@ pub struct Studio {
pub actions: Vec<Action>,
pub settings_path: PathBuf,
pub cache_path: PathBuf,
cache_io: Bridge,
pub cache_busy: bool,
pub cache_status: String,
cache_next: Instant,
pub fg: Bridge,
pub bg: Bridge,
pub io: Bridge,
@ -221,6 +225,10 @@ impl Studio {
actions: vec![],
settings_path,
cache_path,
cache_io: Bridge::with_program(Duration::from_secs(30), worker_program.clone()),
cache_busy: false,
cache_status: String::new(),
cache_next: Instant::now() + Duration::from_secs(60),
fg: Bridge::with_program(Duration::from_secs(30), worker_program.clone()),
bg: Bridge::with_program(Duration::from_secs(30), worker_program.clone()),
io,
@ -708,7 +716,52 @@ impl Studio {
t.presentation_fullscreen
})
}
pub fn clean_cache(&mut self, manual: bool) {
if self.cache_busy || !self.initialized || self.loading {
return;
}
let protected = self.deck.iter().map(|d| d.key.clone()).collect();
if self.cache_io.submit(
0,
0,
Request::CleanCache {
path: self.cache_path.clone(),
policy: self.settings.disk_cache.clone(),
protected,
manual,
},
) {
self.cache_busy = true;
self.cache_status = "Cleaning disk cache…".into();
}
}
pub fn remember_cache_policy(&mut self) {
self.save_preferences();
self.cache_next = Instant::now() + Duration::from_secs(2);
}
pub fn poll(&mut self) {
while let Ok(c) = self.cache_io.rx.try_recv() {
self.cache_busy = false;
self.cache_next = Instant::now() + Duration::from_secs(60);
self.cache_status = match c.result {
Ok(p) => match (p.reply.error, p.reply.cleanup) {
(Some(e), _) => format!("Cache cleanup: {e}"),
(_, Some(r)) => format!(
"Disk cache: {} MiB remaining; removed {} files ({} MiB); {} protected/changed files retained.",
r.remaining_bytes.div_ceil(1024 * 1024),
r.removed_files,
r.removed_bytes.div_ceil(1024 * 1024),
r.skipped_files
),
_ => "Cache cleanup returned no report.".into(),
},
Err(e) => format!("Cache cleanup: {e}"),
};
}
if Instant::now() >= self.cache_next {
self.clean_cache(false);
}
while let Ok(completion) = self.notes_io.rx.try_recv() {
if completion.generation != self.generation {
continue;

View File

@ -71,6 +71,12 @@ pub enum Request {
},
ReadFrame(PathBuf),
LoadSettings(PathBuf),
CleanCache {
path: PathBuf,
policy: crate::cache::Policy,
protected: Vec<String>,
manual: bool,
},
SaveSettings {
path: PathBuf,
settings: Box<Settings>,
@ -94,6 +100,7 @@ pub struct Reply {
pub bytes: usize,
pub edge: Option<u32>,
pub cached: bool,
pub cleanup: Option<crate::cache::Report>,
}
pub struct ResultPacket {
pub reply: Reply,
@ -285,6 +292,20 @@ pub fn run() -> Result<(), String> {
});
data = rgba;
}
Request::CleanCache {
path,
policy,
protected,
manual,
} => {
reply.cleanup = Some(crate::cache::clean(
&path,
&policy,
&protected,
manual,
std::time::SystemTime::now(),
)?);
}
Request::LoadSettings(path) => reply.settings = Some(settings::read(&path)?),
Request::SaveSettings { path, settings } => settings::write(&path, &settings)?,
Request::Pick { folder, owner } => {

View File

@ -0,0 +1,202 @@
mod common;
use pdf_presenter::{
cache::{self, Policy},
document::Document,
settings,
studio::Studio,
};
use std::{
fs::{self, File, FileTimes},
path::{Path, PathBuf},
time::{Duration, Instant, SystemTime},
};
fn entry(root: &Path, project: u8, page: u8, bytes: u64, age_days: u64) -> PathBuf {
let dir = root
.join(format!("{project:064x}"))
.join(format!("{:064x}", 1));
fs::create_dir_all(&dir).unwrap();
let path = dir.join(format!("{page}-512-hayro09.rgba"));
let f = File::create(&path).unwrap();
f.set_len(bytes).unwrap();
f.set_times(
FileTimes::new().set_modified(SystemTime::now() - Duration::from_secs(age_days * 86400)),
)
.unwrap();
path
}
#[test]
fn expiration_and_quota_remove_oldest_and_protect_active_projects() {
let temp = tempfile::tempdir().unwrap();
let root = temp.path();
let old = entry(root, 1, 0, 1024, 40);
let older = entry(root, 1, 1, 40 * 1024 * 1024, 3);
let newer = entry(root, 2, 0, 40 * 1024 * 1024, 2);
let protected = entry(root, 3, 0, 10 * 1024 * 1024, 40);
let locked = entry(root, 4, 0, 1024, 40);
let lease = cache::lease(root, &format!("{:064x}", 4)).unwrap();
let policy = Policy {
max_mib: 64,
max_days: 30,
};
let r = cache::clean(
root,
&policy,
&[format!("{:064x}", 3)],
false,
SystemTime::now(),
)
.unwrap();
assert_eq!(r.removed_files, 2);
assert!(!old.exists() && !older.exists());
assert!(newer.exists() && protected.exists() && locked.exists());
assert_eq!(r.remaining_bytes, 50 * 1024 * 1024 + 1024);
assert_eq!(r.skipped_files, 2);
drop(lease);
let r = cache::clean(root, &policy, &[], true, SystemTime::now()).unwrap();
assert_eq!(r.removed_files, 3);
assert_eq!(r.remaining_bytes, 0);
}
#[test]
fn unknown_files_symlinks_missing_roots_and_invalid_policies_are_safe() {
let temp = tempfile::tempdir().unwrap();
let root = temp.path().join("cache");
assert_eq!(
cache::clean(&root, &Policy::default(), &[], true, SystemTime::now())
.unwrap()
.removed_files,
0
);
let file = entry(&root, 1, 0, 3, 50);
let unknown = file.with_file_name("notes.json");
fs::write(&unknown, "private notes").unwrap();
#[cfg(unix)]
{
std::os::unix::fs::symlink(&unknown, file.with_file_name("1-512-hayro09.rgba")).unwrap();
std::os::unix::fs::symlink(file.parent().unwrap(), root.join(format!("{:064x}", 2)))
.unwrap();
}
cache::clean(&root, &Policy::default(), &[], true, SystemTime::now()).unwrap();
assert!(unknown.exists());
assert!(!file.exists());
assert!(
Policy {
max_mib: 0,
max_days: 30
}
.validate()
.is_err()
);
assert!(
Policy {
max_mib: 64,
max_days: 0
}
.validate()
.is_err()
);
assert!(
Policy {
max_mib: 1048577,
max_days: 30
}
.validate()
.is_err()
);
assert!(
Policy {
max_mib: 64,
max_days: 3651
}
.validate()
.is_err()
);
}
#[test]
fn settings_migrate_validate_and_round_trip() {
let temp = tempfile::tempdir().unwrap();
let path = temp.path().join("settings.toml");
fs::write(&path, "version = 1").unwrap();
let mut s = settings::read(&path).unwrap();
assert_eq!(s.disk_cache.max_mib, 10240);
assert_eq!(s.disk_cache.max_days, 30);
s.disk_cache = Policy {
max_mib: 256,
max_days: 7,
};
settings::write(&path, &s).unwrap();
let s = settings::read(&path).unwrap();
assert_eq!(s.disk_cache.max_mib, 256);
assert_eq!(s.disk_cache.max_days, 7);
fs::write(&path, "version=1\n[disk_cache]\nmax_days=0").unwrap();
assert!(settings::read(&path).is_err());
let example = Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../docs/interfaces/examples/settings-v1.toml");
settings::read(&example).unwrap();
}
#[test]
fn manual_worker_cleanup_preserves_live_document_and_regenerates_after_expunging() {
let temp = tempfile::tempdir().unwrap();
let images = temp.path().join("images");
fs::create_dir(&images).unwrap();
common::image(&images.join("1.png"), [20, 40, 60, 255]);
let root = temp.path().join("cache");
let doc = Document::open(&images, root.clone()).unwrap();
let frame = doc.render(0, 512).unwrap();
let mut studio = Studio::with_program(true, None, env!("CARGO_BIN_EXE_pdf-presenter").into());
studio.cache_path = root.clone();
studio.initialized = true;
let clean = |s: &mut Studio| {
s.clean_cache(true);
assert!(s.cache_busy);
let deadline = Instant::now() + Duration::from_secs(10);
while s.cache_busy {
s.poll();
assert!(Instant::now() < deadline, "{}", s.cache_status);
std::thread::sleep(Duration::from_millis(5));
}
assert!(
s.cache_status.starts_with("Disk cache:"),
"{}",
s.cache_status
);
};
clean(&mut studio);
assert!(frame.info.path.exists());
drop(doc);
clean(&mut studio);
assert!(!frame.info.path.exists());
let doc = Document::open(&images, root).unwrap();
assert_eq!(frame.rgba, doc.render(0, 512).unwrap().rgba);
}
#[test]
fn changed_policy_triggers_background_expiration_and_errors_are_reported() {
let temp = tempfile::tempdir().unwrap();
let root = temp.path().join("cache");
let expired = entry(&root, 1, 0, 30, 40);
let fresh = entry(&root, 1, 1, 30, 0);
let mut s = Studio::with_program(true, None, env!("CARGO_BIN_EXE_pdf-presenter").into());
s.cache_path = root;
s.initialized = true;
s.remember_cache_policy();
let deadline = Instant::now() + Duration::from_secs(10);
while !s.cache_status.starts_with("Disk cache:") {
s.poll();
assert!(Instant::now() < deadline, "{}", s.cache_status);
std::thread::sleep(Duration::from_millis(10));
}
assert!(!expired.exists());
assert!(fresh.exists());
s.cache_path = fresh;
s.clean_cache(true);
while s.cache_busy {
s.poll();
assert!(Instant::now() < deadline);
std::thread::sleep(Duration::from_millis(10));
}
assert!(
s.cache_status.contains("not a regular directory"),
"{}",
s.cache_status
);
}

View File

@ -526,6 +526,13 @@ fn nested_settings_remain_interactive_and_menu_still_dismisses() {
);
assert_eq!(s.settings.auto_show, !auto_show);
assert!(s.menu_open);
click(&mut s, "Disk cache");
click(&mut s, "Maximum total size (MiB)");
click(&mut s, "Expire after (days since rendering)");
click(&mut s, "Expunge unused cache now");
assert!(s.cache_busy, "The Preferences button must submit cleanup");
assert!(s.menu_open);
click(&mut s, "Disk cache");
click(&mut s, "Storage locations");
assert!(s.menu_open);
click(&mut s, "Reset timer");

View File

@ -2,6 +2,16 @@
## Unreleased
### 0.1.70
- Add configurable disk-cache size and lifetime limits (10 GiB / 30 days by
default) and manual expunge under Preferences. A supervised background worker
removes expired/oldest artifacts, protects active decks with process locks,
reports reclaimed space and errors, and preserves source files and notes.
Linux formatting, warnings-denied Clippy/rustdoc, workspace/native tests and
13 Python tests pass; whole-application coverage is 84.39% (75% floor).
Windows/macOS checks and physical-display acceptance were not run.
### 0.1.69
- Decode the unsupported-platform keep-awake child status with the private

View File

@ -100,8 +100,8 @@ benchmark or comparison against Pympress. The source PDF remains untracked and u
- Idle-timeout, AC/battery, blank-state and crash-release sleep checks on each OS.
- Automatic reconnect to an orphan output host; Windows worker memory job limits;
per-output process isolation where one display driver can stall a shared host.
- Automatic disk cache quota/eviction and an unwritable-cache memory fallback.
Current disk cache needs manual cleanup while closed; failures retain prior output.
- Unwritable-cache memory fallback. Since 0.1.70 disk cache maintenance supports
size/age limits and manual expunge, preserving active decks; failures retain output.
- Explicit slide/notes-region cropping for notes-page PDFs, broader bundled CJK font
coverage and pathological notes-layout latency. Current PDF notes are annotation
Contents, not inferred speaker text embedded as page graphics.

View File

@ -11,14 +11,15 @@ T06 bundled renderer/codecs (Hayro replaces PDFium); T07 bounded pipes; T08 real
T08a folders; T09 priorities; T10 worker deadlines; T11/T12 verified atomic caches;
T13 bounded decoded cache; T14 software composition; T16 approved presenter/browser
workflow; T17 asynchronous annotation/sidecar notes; T18 last-frame crash hold and
blanked output-host restart. T01 full latency instrumentation, T15 disk quota,
blanked output-host restart. 0.1.70 adds T15 disk size/age cleanup with active-deck
protection and manual expunge. T01 full latency instrumentation,
T17 explicit notes-region crop, T18 reconnect, platform acceptance and clean-machine
release checks remain open. Do not mark their broader acceptance from this code alone.
0.1.13 adds whole-deck processed-frame reuse and RAM preparation to T09/T12/T13:
two workers, screen-derived resolution, cache-first opening, retained complete buffers,
explicit preparation progress/ETA and memory-pressure pause. T01's full optical
latency matrix and T15's persistent disk quota remain open.
latency matrix remains open; T15's persistent disk quota was added in 0.1.70.
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

View File

@ -9,6 +9,10 @@ presentation_fullscreen = true
thumbnail_size = 220.0
buffer_mib = 1024
[disk_cache]
max_mib = 10240
max_days = 30
[slide_colors]
page_background = [255, 255, 255]
fit_padding = [0, 0, 0]

View File

@ -54,4 +54,43 @@ Stale reads for evicted entries are discarded. READY requires the whole deck to
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.
## Disk retention — 0.1.70
Menu → Preferences → Disk cache controls total size (default 10240 MiB / 10 GiB)
and lifetime (default 30 days), with **Expunge unused cache now** to remove all
eligible artifacts regardless of age/size. One day is 86400 seconds. Age is measured
from filesystem modification time (render/write time), not access time; warm reads
do not extend lifetime. Future timestamps do not expire until their age reaches
the limit. Expired files are removed first in oldest-first order, then older files
are removed until total bytes are within the target. Ties sort by path.
A dedicated killable worker starts maintenance 60 seconds after startup and repeats
60 seconds after completion; option changes schedule it after two seconds. Loading
a document defers submission. Cleanup never blocks first-page display or UI input.
Only one cleanup request is admitted per presenter; its deadline is 30 seconds.
Errors/timeouts appear in the Disk cache section and retry on the next interval.
Manual cleanup reports removed files/bytes, remaining bytes and retained candidates.
Counts are a scan snapshot; concurrent rendering can change actual usage.
Current presenter projects are excluded. Live document workers also hold shared OS
locks on `<project-key>/.lease-v1`; cleanup takes a nonblocking exclusive lock before
deleting each file. Locks release on process exit, including crashes. This protects
workers opening/rendering decks across instances. Lease files are empty, contain no
persistent fields, are never unlinked, and support old caches by lazy creation.
Older application versions do not honor these locks: avoid concurrent mixed-version
use of one cache. Active decks can exceed the quota or lifetime; limits are eventual
targets, not a hard write cap. Manual expunge also retains active projects. To clear
the current deck, close the application and delete `slides-v1`, or reopen the app
without a deck and use manual expunge.
The scan is fixed to project/source-hash directories, never follows discovered
symlinks, and caps traversal at 200000 entries before deletion. It deletes only known
page/edge `hayro09` and `hayro09-straight` RGBA files and extraction manifests;
unknown files and temporary files are retained. Total bytes count all regular files
at the artifact level, including unknown files, but exclude filesystem overhead and
empty lease files. Unknown files or protected decks can prevent reaching the target.
Metadata is rechecked under the project lock before deletion. Empty source-hash
directories are removed when possible; project/lease directories remain. Image and
manifest deletion is individually recoverable: missing artifacts regenerate.
Source documents, notes sidecars and settings are outside cleanup scope. A full or
unwritable disk still reports an explicit error; a memory-only fallback is pending.

View File

@ -196,3 +196,11 @@ lets the current preview use that aspect ratio, without transferring image data.
Missing/zero dimensions or a route/fullscreen mismatch fall back to the connected
monitor size. Reports are refreshed by the existing one-second heartbeat, and are
not persisted. Outputs with different aspect ratios still use their own viewport.
## Cache maintenance — 0.1.70
`CleanCache {path, policy: {max_mib, max_days}, protected: [project_key], manual}`
runs on a dedicated 30-second supervised worker, one outstanding job per presenter.
The reply adds optional `cleanup` with unsigned `removed_bytes`, `remaining_bytes`,
`removed_files`, and `skipped_files`. Errors use the existing error field. No frame
payload is transferred. The same-build private protocol requires no migration.

View File

@ -84,6 +84,11 @@ flushed temporary file. Unknown fields are ignored and not preserved on round tr
- `presenter_fullscreen`, `presentation_fullscreen`: booleans, default true.
- `browser_monitor`: optional monitor ID; missing/unavailable means presenter screen.
- `thumbnail_size`: logical width in pixels, finite 100–400; default 220.
- `disk_cache.max_mib`: integer 64–1048576 MiB, default 10240 (10 GiB).
- `disk_cache.max_days`: integer 1–3650 days, default 30. Added in 0.1.70;
missing table/fields in v1 settings use defaults. Invalid limits are rejected.
Global options persist asynchronously; older binaries ignore these fields. See
[cache retention](extraction-cache.md) for age, active-deck protection and cleanup.
- `buffer_mib`: integer 64–16384, adaptive default, 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. Since 0.1.46, missing budgets use 15% of available physical RAM measured once at

View File

@ -384,3 +384,13 @@ render/present on a window, a **Zoom performance** warning appears on the presen
with reset, disable and keep-enabled choices. This is a detected frame-budget
warning, not proof that zoom caused the delay. It does not blank or interrupt the
output. It cannot predict compositor/hardware delays or guarantee a frame rate.
### Disk cache cleanup
In **Menu → Preferences → Disk cache**, set the maximum total size in MiB and
lifetime in days since rendering (defaults: 10 GiB and 30 days). Cleanup runs every
minute, deleting expired files and then the oldest files to meet the size target.
**Expunge unused cache now** clears eligible cached slides immediately in the
background. Active decks are protected and may temporarily exceed either limit.
The cleanup report shows removed and remaining data; deleted slides regenerate
when reopened. Source documents and presenter notes are preserved.