856f865cf98d
spill.rs
//! Scratch disk: tile pixels beyond a memory budget move to a file and come back on access.
//!
//! Every [`Tile`](crate::Tile) keeps its bytes in a [`Cell`]: resident (`Some`) or on disk
//! (`None`, with its [`Extent`] in the scratch file). Readers take the cell's read lock, so a
//! tile in use is never evicted; a spilled tile is read back (LZ4 + CRC-checked) by whoever
//! touches it first.
//!
//! - **Accounting.** [`stats`] counts the bytes of every live tile that is resident, whether or
//! not a scratch disk is configured.
//! - **Eviction** is the clock ("second chance") algorithm over a registry of weak cell
//! pointers: a tile touched since the hand last passed keeps its place once. A background
//! thread evicts down to 90 % of the budget; a thread that pushes memory past 125 % helps.
//! - **Clean tiles are free to drop.** A tile written once and not changed since keeps its
//! extent, so evicting it again only frees memory; changing it frees the extent.
//! - **Off by default.** Until [`configure`] sets a directory and a budget nothing is evicted
//! (tests, the web build).
//!
//! Failures never panic: a scratch write or file creation that fails, or a volume running low
//! on free space, keeps the tile in memory and pauses spilling (reported in
//! [`SpillStats::last_error`]); it is retried with exponential backoff and resumes on its own.
//! [`epoch`] tells owners of memory caps (history) to re-apply them meanwhile. A failed read retains its disk extent and
//! poisons the tile: edits and saves check the health of the document they publish, plus
//! [`check_since`] for failures that came and went during the operation. The
//! infallible display API uses a temporary placeholder, never replacement pixel storage.
//!
//! No lock is held across a call into the scratch folder. Opening and measuring it run on a
//! short-lived query thread, at most one per folder and question; callers wait a bounded time
//! for the answer, and a late answer still applies if that folder is still the configured one.
//! Status reads the UI makes every frame stay fast whatever the folder does.
use std::collections::VecDeque;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
use std::sync::{Arc, Condvar, Mutex, PoisonError, RwLock, RwLockReadGuard, RwLockWriteGuard, Weak};
use std::time::{Duration, Instant};
use crate::scratch_file::{Extent, ScratchFile};
/// One tile's bytes and where they live.
pub(crate) struct Cell {
data: RwLock<Option<Vec<u8>>>,
/// Byte length of the tile (fixed for its lifetime).
len: usize,
error: Mutex<Option<String>>,
/// A copy on disk that matches `data` (kept while the tile is unchanged).
slot: Mutex<Option<(Arc<ScratchFile>, Extent)>>,
/// Touched since the clock hand last passed.
referenced: AtomicBool,
}
impl Cell {
pub(crate) fn new(bytes: Vec<u8>) -> Arc<Cell> {
let len = bytes.len();
let cell = Arc::new(Cell { data: RwLock::new(Some(bytes)), len, error: Mutex::new(None), slot: Mutex::new(None), referenced: AtomicBool::new(true) });
M.live.fetch_add(1, Ordering::Relaxed);
M.resident.fetch_add(len, Ordering::Relaxed);
M.register(&cell);
maybe_evict();
cell
}
pub(crate) fn len(&self) -> usize {
self.len
}
pub(crate) fn read_error(&self) -> Option<String> {
self.error.lock().unwrap_or_else(PoisonError::into_inner).clone()
}
fn set_error(&self, error: Option<String>) {
let mut old = self.error.lock().unwrap_or_else(PoisonError::into_inner);
match (old.is_some(), error.is_some()) {
(false, true) => {
M.failed.fetch_add(1, Ordering::Release);
M.read_errors.fetch_add(1, Ordering::Release);
}
(true, false) => {
// Invalidate computations that started while pixels were unreadable too.
// Publish this before reporting the tile healthy to commit guards.
M.read_errors.fetch_add(1, Ordering::Release);
M.failed.fetch_sub(1, Ordering::Release);
}
_ => {}
}
*old = error;
}
#[inline]
fn touch(&self) {
if !self.referenced.load(Ordering::Relaxed) {
self.referenced.store(true, Ordering::Relaxed);
}
}
/// Read access; reads the tile back from the scratch disk if it was evicted.
pub(crate) fn read(&self) -> RwLockReadGuard<'_, Option<Vec<u8>>> {
let mut loaded_pixels = false;
loop {
self.touch();
let g = self.data.read().unwrap_or_else(PoisonError::into_inner);
if g.is_some() {
if loaded_pixels {
// Pin the tile before eviction: even a budget smaller than one tile
// must not repeatedly evict the pixels this reader just loaded.
maybe_evict();
}
return g;
}
drop(g);
let mut w = self.data.write().unwrap_or_else(PoisonError::into_inner);
let loaded = self.load(&mut w).is_ok();
drop(w);
if !loaded {
return self.data.read().unwrap_or_else(PoisonError::into_inner);
}
loaded_pixels = true;
}
}
/// Write access: resident, and any disk copy is released (it no longer matches).
pub(crate) fn write(&self) -> RwLockWriteGuard<'_, Option<Vec<u8>>> {
self.touch();
let mut w = self.data.write().unwrap_or_else(PoisonError::into_inner);
let loaded = w.is_none();
if self.load(&mut w).is_err() {
// Keep the only original copy. The write guard's temporary placeholder is
// discarded, and the transaction's integrity check refuses to commit it.
return w;
}
if let Some((file, extent)) = self.slot.lock().unwrap_or_else(PoisonError::into_inner).take() {
file.free(extent);
}
if loaded {
// Evicting here could only pick other tiles (this one is locked), so it is safe, and
// a long run of writes to spilled tiles must not outgrow the budget.
maybe_evict();
}
w
}
/// Fill `w` from the scratch disk if it is not resident (`w` is this cell's write guard).
fn load(&self, w: &mut Option<Vec<u8>>) -> Result<(), String> {
if w.is_some() {
return Ok(());
}
let slot = self.slot.lock().unwrap_or_else(PoisonError::into_inner).clone();
let bytes = match slot {
Some((file, extent)) => {
let mut packed = Vec::new();
match file.read_into(extent, &mut packed).map_err(|e| e.to_string()).and_then(|()| unpack(&packed, self.len)) {
Ok(b) => b,
Err(e) => {
let error = format!("scratch read failed ({e}); editing and saving are blocked until the tile is readable");
self.set_error(Some(error.clone()));
M.error(error.clone());
return Err(error);
}
}
}
None => {
let error = "a spilled tile has no scratch copy; editing and saving are blocked".to_string();
self.set_error(Some(error.clone()));
M.error(error.clone());
return Err(error);
}
};
*w = Some(bytes);
self.set_error(None);
M.resident.fetch_add(self.len, Ordering::Relaxed);
M.reloads.fetch_add(1, Ordering::Relaxed);
Ok(())
}
/// Move this tile to disk if nobody is using it. Returns the bytes freed.
fn evict(&self, file: &Arc<ScratchFile>) -> Result<usize, String> {
let Ok(mut w) = self.data.try_write() else { return Ok(0) };
let Some(bytes) = w.as_ref() else { return Ok(0) };
let mut slot = self.slot.lock().unwrap_or_else(PoisonError::into_inner);
if slot.is_none() {
let packed = lz4_flex::block::compress(bytes);
let extent = file.write(&packed).map_err(|e| format!("scratch write to {} failed: {e}", file.path().display()))?;
M.written.fetch_add(packed.len() as u64, Ordering::Relaxed);
*slot = Some((file.clone(), extent));
}
drop(slot);
*w = None;
M.resident.fetch_sub(self.len, Ordering::Relaxed);
M.evictions.fetch_add(1, Ordering::Relaxed);
Ok(self.len)
}
}
impl Drop for Cell {
fn drop(&mut self) {
if self.error.get_mut().unwrap_or_else(PoisonError::into_inner).is_some() {
M.read_errors.fetch_add(1, Ordering::Release);
M.failed.fetch_sub(1, Ordering::Release);
}
if let Some(bytes) = self.data.get_mut().unwrap_or_else(PoisonError::into_inner).take() {
M.resident.fetch_sub(self.len, Ordering::Relaxed);
// The next tile of this size reuses the buffer, as main's pool expects.
crate::scratch::give(bytes);
}
if let Some((file, extent)) = self.slot.get_mut().unwrap_or_else(PoisonError::into_inner).take() {
file.free(extent);
}
M.live.fetch_sub(1, Ordering::Relaxed);
}
}
fn unpack(packed: &[u8], len: usize) -> Result<Vec<u8>, String> {
let mut bytes = crate::scratch::take_exact(len, 0u8);
match lz4_flex::block::decompress_into(packed, &mut bytes) {
Ok(n) if n == len => Ok(bytes),
Ok(n) => {
crate::scratch::give(bytes);
Err(format!("tile decoded to {n} bytes, expected {len}"))
}
Err(e) => {
crate::scratch::give(bytes);
Err(e.to_string())
}
}
}
/// Process-wide state. Plain statics: everything here is const-constructible.
struct Manager {
failed: AtomicUsize,
read_errors: AtomicU64,
resident: AtomicUsize,
live: AtomicUsize,
/// Pixel bytes to keep resident; 0 = spilling off or paused.
budget: AtomicUsize,
/// Spilling is paused after a write, create or free-space failure ([`Config::paused`]).
paused: AtomicBool,
/// Changes whenever spilling turns on or off, so owners of memory caps re-apply them.
epoch: AtomicU64,
/// Scratch bytes allowed before the volume would run low or the size cap is reached.
space_limit: AtomicU64,
/// Re-read the volume's free space once the scratch file grows past this.
next_space_check: AtomicU64,
/// A sweep wrote successfully since the last resume: reset the retry backoff.
recovering: AtomicBool,
/// The last free-space query for the scratch directory got no answer.
space_unmeasured: AtomicBool,
registry: Mutex<Registry>,
config: Mutex<Config>,
evictions: AtomicU64,
reloads: AtomicU64,
written: AtomicU64,
}
struct Registry {
cells: Vec<Weak<Cell>>,
hand: usize,
}
struct Config {
dir: Option<PathBuf>,
/// Opened at configuration time; startup also reaps abandoned Unix files.
file: Option<Arc<ScratchFile>>,
last_error: Option<String>,
/// The budget [`configure`] / [`set_budget`] asked for; restored when a pause ends.
budget: usize,
paused: Option<Pause>,
/// Delay before the next retry; doubles per failed retry up to [`RETRY_MAX`].
backoff: Duration,
/// Explicit scratch size limit ([`set_size_cap`]); the free-space reserve always applies.
size_cap: Option<u64>,
/// Scratch bytes the volume allows, as of the last answer; `None` = unmeasured.
room: Option<u64>,
}
struct Pause {
message: String,
retry_at: Instant,
}
const RETRY_FIRST: Duration = Duration::from_secs(1);
const RETRY_MAX: Duration = Duration::from_secs(60);
/// Re-check free space after this much scratch growth.
const SPACE_CHECK_EVERY: u64 = 64 << 20;
/// Leave at least max(1 GiB, 5 % of the volume) free for the system and other programs.
const RESERVE_MIN: u64 = 1 << 30;
/// How long a caller waits for the scratch folder to answer. A healthy disk answers in far less;
/// the query goes on after this and its answer still counts when it comes.
const QUERY_WAIT: Duration = Duration::from_secs(2);
/// Most folder queries in flight at once. A system call on a dead hard mount can't be cancelled,
/// so each stuck one keeps its thread, and every other folder tried on that mount adds one.
const MAX_QUERIES: usize = 16;
/// A question in flight about a scratch folder (open it and/or measure it).
struct Query {
dir: PathBuf,
prepare: bool,
deadline: Instant,
done: Arc<QueryDone>,
}
/// Set once a query's answer has been applied (or discarded).
#[derive(Default)]
struct QueryDone {
finished: Mutex<bool>,
wake: Condvar,
}
impl QueryDone {
fn finish(&self) {
*self.finished.lock().unwrap_or_else(PoisonError::into_inner) = true;
self.wake.notify_all();
}
fn finished(&self) -> bool {
*self.finished.lock().unwrap_or_else(PoisonError::into_inner)
}
/// Wait until the query finishes or `deadline` passes; a deadline already past returns at once.
fn wait_until(&self, deadline: Instant) {
let Some(left) = deadline.checked_duration_since(Instant::now()) else { return };
let done = self.finished.lock().unwrap_or_else(PoisonError::into_inner);
drop(self.wake.wait_timeout_while(done, left, |done| !*done).unwrap_or_else(PoisonError::into_inner));
}
}
static QUERIES: Mutex<Vec<Query>> = Mutex::new(Vec::new());
/// Query threads alive, counted until they finish, including closing any file they opened;
/// `QUERIES` only dedupes questions.
static QUERY_THREADS: AtomicUsize = AtomicUsize::new(0);
static QUERY_HOOK: RwLock<Option<fn(&Path)>> = RwLock::new(None);
static M: Manager = Manager {
failed: AtomicUsize::new(0),
read_errors: AtomicU64::new(0),
resident: AtomicUsize::new(0),
live: AtomicUsize::new(0),
budget: AtomicUsize::new(0),
paused: AtomicBool::new(false),
epoch: AtomicU64::new(0),
space_limit: AtomicU64::new(u64::MAX),
next_space_check: AtomicU64::new(0),
recovering: AtomicBool::new(false),
space_unmeasured: AtomicBool::new(false),
registry: Mutex::new(Registry { cells: Vec::new(), hand: 0 }),
config: Mutex::new(Config { dir: None, file: None, last_error: None, budget: 0, paused: None, backoff: RETRY_FIRST, size_cap: None, room: None }),
evictions: AtomicU64::new(0),
reloads: AtomicU64::new(0),
written: AtomicU64::new(0),
};
impl Manager {
fn register(&self, cell: &Arc<Cell>) {
let mut r = self.registry.lock().unwrap_or_else(PoisonError::into_inner);
r.cells.push(Arc::downgrade(cell));
// Drop the pointers of freed tiles once they outnumber the live ones.
if r.cells.len() > self.live.load(Ordering::Relaxed).saturating_mul(2).saturating_add(4096) {
r.cells.retain(|w| w.strong_count() > 0);
r.hand = 0;
}
}
fn config(&self) -> std::sync::MutexGuard<'_, Config> {
self.config.lock().unwrap_or_else(PoisonError::into_inner)
}
fn error(&self, msg: String) {
log_error(&msg);
self.config().last_error = Some(msg);
}
/// Set the active budget, bumping [`epoch`] when spilling turns on or off.
fn set_active(&self, budget: usize) {
let old = self.budget.swap(budget, Ordering::AcqRel);
if (old > 0) != (budget > 0) {
self.epoch.fetch_add(1, Ordering::AcqRel);
}
}
/// Pause spilling after a failure: every tile stays in memory (owners re-apply their
/// memory caps through [`epoch`]) and a retry is scheduled with exponential backoff.
fn pause(&self, c: &mut Config, reason: &str) {
let wait = c.backoff;
c.backoff = c.backoff.saturating_mul(2).min(RETRY_MAX);
let message = format!("{reason}; spilling is paused (tiles stay in memory), retrying in {} s", wait.as_secs());
log_error(&message);
c.last_error = Some(message.clone());
c.paused = Some(Pause { message, retry_at: Instant::now().checked_add(wait).unwrap_or_else(Instant::now) });
self.recovering.store(false, Ordering::Relaxed);
self.paused.store(true, Ordering::Release);
self.set_active(0);
}
/// End a pause: the directory is usable and has room again.
fn resume(&self, c: &mut Config) {
if let Some(p) = c.paused.take()
&& c.last_error.as_deref() == Some(p.message.as_str())
{
c.last_error = None;
}
self.paused.store(false, Ordering::Release);
self.recovering.store(true, Ordering::Relaxed);
self.set_active(c.budget);
}
/// Apply a finished folder query. `file` is the scratch file a `prepare` query opened (or the
/// error), `sampled_used` the scratch bytes in use just before the volume was asked, `space`
/// what the volume reported. Discarded if the folder changed meanwhile.
fn settle(&self, dir: &Path, prepare: bool, file: Option<std::io::Result<ScratchFile>>, sampled_used: u64, space: Option<(u64, u64)>, done: &QueryDone) {
// Declared before the guard so a rejected file closes after the lock is released.
let mut _spare: Option<ScratchFile> = None;
let mut c = self.config();
// Under the config lock, so a caller holding the lock can tell answered from not.
done.finish();
if c.dir.as_deref() != Some(dir) {
return;
}
match file {
Some(Ok(f)) if c.file.is_none() => c.file = Some(Arc::new(f)),
Some(Ok(f)) => _spare = Some(f),
Some(Err(e)) if c.file.is_none() => {
self.pause(&mut c, &format!("could not create a scratch file in {}: {e}", dir.display()));
return;
}
Some(Err(_)) | None => {}
}
let used = c.file.as_ref().map_or(0, |f| f.used());
apply_space(&mut c, sampled_used, space);
if !prepare {
return;
}
if c.file.is_none() {
// The folder changed away and back while this ran.
self.pause(&mut c, ¬_responding(dir));
return;
}
if used >= self.space_limit.load(Ordering::Relaxed) {
let msg = no_room(dir, c.size_cap);
self.pause(&mut c, &msg);
return;
}
if c.paused.is_some() {
self.resume(&mut c);
}
}
/// Open the scratch file and check its volume's room, waiting up to [`QUERY_WAIT`]; an answer
/// that comes later is applied by [`Manager::settle`]. Pauses (and says why) on failure or
/// silence. The caller holds no lock.
fn prepare(&self, dir: &Path) {
let done = ask(dir, true);
let mut c = self.config();
if c.dir.as_deref() != Some(dir) || done.as_ref().is_some_and(|d| d.finished()) {
return;
}
// No answer in time: it still counts when it comes. Until then:
let used = c.file.as_ref().map_or(0, |f| f.used());
apply_space(&mut c, used, None);
if c.file.is_none() || c.paused.is_some() {
self.pause(&mut c, ¬_responding(dir));
}
}
/// Measure the volume's free space, waiting up to [`QUERY_WAIT`]. The caller holds no lock.
fn measure(&self, dir: &Path) {
let done = ask(dir, false);
let mut c = self.config();
if c.dir.as_deref() != Some(dir) || done.as_ref().is_some_and(|d| d.finished()) {
return;
}
let used = c.file.as_ref().map_or(0, |f| f.used());
apply_space(&mut c, used, None);
}
/// Retry a paused scratch disk once its backoff has elapsed. Cheap when not paused.
fn retry(&self) {
if !self.paused.load(Ordering::Acquire) {
return;
}
let c = self.config();
let due = c.paused.as_ref().is_some_and(|p| Instant::now() >= p.retry_at);
if !due {
return;
}
self.retry_now(c);
}
/// Retry a paused scratch disk now (the guard is released before the folder is asked).
fn retry_now(&self, mut c: std::sync::MutexGuard<'_, Config>) {
let dir = match c.dir.clone() {
Some(dir) if c.budget > 0 => dir,
_ => {
c.paused = None;
self.paused.store(false, Ordering::Release);
return;
}
};
// Push the next retry out so other threads don't all wait on this one.
let wait = c.backoff;
if let Some(p) = &mut c.paused {
p.retry_at = Instant::now().checked_add(wait).unwrap_or_else(Instant::now);
}
drop(c);
self.prepare(&dir);
}
/// The scratch file, if spilling is on and the volume still has room.
fn file(&self) -> Option<Arc<ScratchFile>> {
if self.budget.load(Ordering::Relaxed) == 0 {
return None;
}
self.config().file.clone()
}
/// Whether the scratch file may grow further; asks for free space every
/// [`SPACE_CHECK_EVERY`] bytes (in the background, never waiting) and pauses spilling when the
/// volume runs low.
fn has_room(&self, file: &ScratchFile) -> bool {
let used = file.used();
if used < self.next_space_check.load(Ordering::Relaxed) && used < self.space_limit.load(Ordering::Relaxed) {
return true;
}
let mut c = self.config();
let Some(dir) = c.dir.clone() else { return false };
if used < self.space_limit.load(Ordering::Relaxed) {
// Ask in the background: this can be any thread, the UI's too. The answer moves the limit.
drop(c);
let query = start_query(&dir, false);
let c = self.config();
// A rejected request must remain due. Don't overwrite a new folder's state or an
// answer that arrived before this lock was reacquired.
if c.dir.as_deref() == Some(dir.as_path()) && !query.as_ref().is_some_and(|(done, _)| done.finished()) {
if query.is_some() {
self.next_space_check.store(used.saturating_add(SPACE_CHECK_EVERY), Ordering::Relaxed);
} else {
self.space_unmeasured.store(true, Ordering::Relaxed);
}
}
return true;
}
if c.paused.is_none() {
let msg = no_room(&dir, c.size_cap);
self.pause(&mut c, &msg);
}
false
}
/// Evict until resident memory is at most `target` or `max_scan` cells were looked at.
/// Returns the bytes freed.
fn sweep(&self, target: usize, max_scan: usize) -> usize {
let Some(file) = self.file() else { return 0 };
let mut freed = 0;
let mut scanned = 0;
while self.resident.load(Ordering::Relaxed) > target && scanned < max_scan {
// Pick victims under the registry lock (cheap), evict them after releasing it.
let mut victims = Vec::with_capacity(64);
{
let mut r = self.registry.lock().unwrap_or_else(PoisonError::into_inner);
let mut i = 0;
while victims.len() < 64 && i < 4096 && !r.cells.is_empty() {
if r.hand >= r.cells.len() {
r.hand = 0;
}
let h = r.hand;
i += 1;
match r.cells.get(h).and_then(Weak::upgrade) {
None => {
r.cells.swap_remove(h);
continue;
}
Some(cell) => {
r.hand += 1;
if cell.referenced.swap(false, Ordering::Relaxed) {
continue;
}
if cell.data.try_read().is_ok_and(|d| d.is_some()) {
victims.push(cell);
}
}
}
}
scanned += i;
if i == 0 {
break;
}
}
for cell in victims {
if !self.has_room(&file) {
return freed;
}
match cell.evict(&file) {
Ok(n) => freed += n,
Err(e) => {
// Disk full or gone: keep tiles in memory until a retry succeeds.
let mut c = self.config();
if c.paused.is_none() {
self.pause(&mut c, &e);
}
return freed;
}
}
}
}
if freed > 0 && self.recovering.swap(false, Ordering::Relaxed) {
self.config().backoff = RETRY_FIRST;
}
freed
}
}
/// Record a volume's answer (`None` = it didn't say) and derive the growth limit from it.
fn apply_space(c: &mut Config, used: u64, space: Option<(u64, u64)>) {
M.space_unmeasured.store(space.is_none(), Ordering::Relaxed);
c.room = space.map(|(available, total)| used.saturating_add(available.saturating_sub(RESERVE_MIN.max(total / 20))));
store_limit(c);
M.next_space_check.store(used.saturating_add(SPACE_CHECK_EVERY), Ordering::Relaxed);
}
/// Publish the scratch size the volume and the size limit allow.
fn store_limit(c: &Config) {
let room = c.room.unwrap_or(u64::MAX);
M.space_limit.store(c.size_cap.map_or(room, |cap| cap.min(room)), Ordering::Relaxed);
}
fn not_responding(dir: &Path) -> String {
format!("scratch disk {} is not responding", dir.display())
}
/// Start (or join) a query about `dir`: the same question is never asked by a second thread, and
/// at most [`MAX_QUERIES`] run at once. `None` if no thread could be started.
fn start_query(dir: &Path, prepare: bool) -> Option<(Arc<QueryDone>, Instant)> {
let mut queries = QUERIES.lock().unwrap_or_else(PoisonError::into_inner);
if let Some(q) = queries.iter().find(|q| q.prepare == prepare && q.dir.as_path() == dir) {
return Some((q.done.clone(), q.deadline));
}
if QUERY_THREADS.load(Ordering::Acquire) >= MAX_QUERIES {
return None;
}
let now = Instant::now();
let deadline = now.checked_add(QUERY_WAIT).unwrap_or(now);
let done = Arc::new(QueryDone::default());
queries.push(Query { dir: dir.to_path_buf(), prepare, deadline, done: done.clone() });
let (job_dir, job_done) = (dir.to_path_buf(), done.clone());
QUERY_THREADS.fetch_add(1, Ordering::AcqRel);
let spawned = std::thread::Builder::new().name("pc-scratch-query".into()).spawn(move || run_query(job_dir, prepare, job_done));
if spawned.is_err() {
QUERY_THREADS.fetch_sub(1, Ordering::AcqRel);
queries.pop();
return None;
}
Some((done, deadline))
}
/// Ask about `dir` and wait up to [`QUERY_WAIT`] for the answer. The caller holds no lock.
fn ask(dir: &Path, prepare: bool) -> Option<Arc<QueryDone>> {
let (done, deadline) = start_query(dir, prepare)?;
done.wait_until(deadline);
Some(done)
}
/// The query thread: touches the folder, then hands the answer to [`Manager::settle`].
fn run_query(dir: PathBuf, prepare: bool, done: Arc<QueryDone>) {
let hook = *QUERY_HOOK.read().unwrap_or_else(PoisonError::into_inner);
if let Some(hook) = hook {
hook(&dir);
}
// Before measuring: writes made during the query come off the free space and must not be
// counted again on top of it. Another folder's file says nothing about this one.
let (open, used) = {
let c = M.config();
let current = c.file.as_ref().filter(|_| c.dir.as_deref() == Some(dir.as_path()));
(prepare && current.is_none(), current.map_or(0, |f| f.used()))
};
let file = open.then(|| std::fs::create_dir_all(&dir).and_then(|()| ScratchFile::create(&dir)));
let space = free_space(&dir);
// Forget it first: a caller that joined it can rely on the answer, and a later caller asks anew.
QUERIES.lock().unwrap_or_else(PoisonError::into_inner).retain(|q| !Arc::ptr_eq(&q.done, &done));
M.settle(&dir, prepare, file, used, space, &done);
QUERY_THREADS.fetch_sub(1, Ordering::AcqRel);
}
/// Whether a query about `dir` is past its wait without an answer.
fn query_overdue(dir: Option<&Path>) -> bool {
let Some(dir) = dir else { return false };
let now = Instant::now();
let queries = QUERIES.lock().unwrap_or_else(PoisonError::into_inner);
queries.iter().any(|q| q.dir.as_path() == dir && now >= q.deadline)
}
/// Scratch files on their way out, oldest first.
struct Retired {
files: VecDeque<(Arc<ScratchFile>, Arc<QueryDone>)>,
/// Closer threads alive.
closers: usize,
}
/// Most closer threads at once: enough that one close stuck on a dead mount doesn't hold up the
/// files behind it, few enough that stuck closes can't pile up threads.
const MAX_CLOSERS: usize = 4;
static RETIRED: Mutex<Retired> = Mutex::new(Retired { files: VecDeque::new(), closers: 0 });
/// Let go of a scratch file off this thread: the last reference closes it, which can flush to its
/// folder, and a dead mount blocks that, while leaving a dead folder is how a user recovers. The
/// returned handle finishes when this reference is gone.
fn retire(file: Arc<ScratchFile>) -> Arc<QueryDone> {
let done = Arc::new(QueryDone::default());
let mut retired = RETIRED.lock().unwrap_or_else(PoisonError::into_inner);
retired.files.push_back((file, done.clone()));
// If no thread can start, the file waits in the queue for the next one rather than closing here.
if retired.closers < MAX_CLOSERS && std::thread::Builder::new().name("pc-scratch-close".into()).spawn(close_retired).is_ok() {
retired.closers += 1;
}
done
}
fn close_retired() {
loop {
let next = {
let mut retired = RETIRED.lock().unwrap_or_else(PoisonError::into_inner);
let next = retired.files.pop_front();
if next.is_none() {
retired.closers = retired.closers.saturating_sub(1);
}
next
};
let Some((file, done)) = next else { return };
drop(file);
done.finish();
}
}
fn no_room(dir: &Path, cap: Option<u64>) -> String {
match cap {
Some(cap) => format!("scratch disk {} reached its size limit ({} MB) or is low on free space", dir.display(), cap >> 20),
None => format!("scratch disk {} is low on free space", dir.display()),
}
}
/// (available, total) bytes of the volume holding `dir`, asked of the directory itself so that a
/// network folder or any other mount reports its own numbers: `GetDiskFreeSpaceEx` on Windows,
/// `statvfs` on Unix. Available is what the current user can write (per-user quotas on Windows, the
/// root reserve on Unix). `None` if the system can't say (the query failed, or it reports a total
/// of zero, as some FUSE and WebDAV mounts do), which disables only the free-space check, not
/// spilling; [`free_space_unmeasured`] tells the user.
#[cfg(any(unix, windows))]
fn free_space(dir: &Path) -> Option<(u64, u64)> {
let dir = std::fs::canonicalize(dir).ok()?;
let (available, total) = volume_space(&dir)?;
known_space(with_purgeable_space(&dir, available, total), total)
}
/// A zero total means the system could not say (a failed query, or a mount that reports no
/// capacity); treating that as an empty disk would pause spilling, so it counts as unknown.
#[cfg(any(unix, windows))]
fn known_space(available: u64, total: u64) -> Option<(u64, u64)> {
(total != 0).then_some((available, total))
}
/// (available, total) bytes of the volume holding `dir`, from `statvfs`.
#[cfg(unix)]
fn volume_space(dir: &Path) -> Option<(u64, u64)> {
let vfs = rustix::io::retry_on_intr(|| rustix::fs::statvfs(dir)).ok()?;
Some((vfs.f_bavail.saturating_mul(vfs.f_frsize), vfs.f_blocks.saturating_mul(vfs.f_frsize)))
}
/// (available, total) bytes of the volume holding `dir`, from `GetDiskFreeSpaceEx`. `dir` is
/// canonical, so verbatim (`\\?\C:\x`, `\\?\UNC\server\share\x`), which also reaches paths past
/// MAX_PATH and keeps trailing dots significant; winsafe takes `&str`, so a non-UTF-8 folder name
/// uses its nearest UTF-8 ancestor (the same volume unless a mount point has such a name).
#[cfg(windows)]
fn volume_space(dir: &Path) -> Option<(u64, u64)> {
disk_free_space(dir.ancestors().find_map(Path::to_str)?)
}
#[cfg(windows)]
fn disk_free_space(dir: &str) -> Option<(u64, u64)> {
// GetDiskFreeSpaceEx requires the trailing backslash on UNC paths.
let arg = if dir.ends_with('\\') { dir.to_string() } else { format!("{dir}\\") };
let (mut available, mut total) = (0, 0);
winsafe::GetDiskFreeSpaceEx(Some(&arg), Some(&mut available), Some(&mut total), None).ok()?;
Some((available, total))
}
/// `statvfs` doesn't count purgeable space (local snapshots and caches macOS frees on demand) but
/// sysinfo does: when the listed disk with the longest mount point holding `dir` is this volume,
/// use its available figure. A listed disk counts as this volume when the mount point's own
/// `statvfs` gives the same numbers (APFS volumes in one container share them, and firmlinks give
/// `/Users` and `/` different device ids, so ids can't be compared); a change between the two
/// readings just keeps the `statvfs` figure. sysinfo asks every mounted volume for its properties,
/// so an unrelated dead mount must not hold up this measurement: the lookup runs on a helper thread
/// that is waited for at most [`PURGEABLE_WAIT`]. Never fails.
#[cfg(target_os = "macos")]
fn with_purgeable_space(dir: &Path, available: u64, total: u64) -> u64 {
static LISTING: AtomicBool = AtomicBool::new(false);
// A listing already running may be stuck on some mount: don't start another.
if LISTING.swap(true, Ordering::AcqRel) {
return available;
}
let dir = dir.to_path_buf();
let (tx, rx) = std::sync::mpsc::channel();
let spawned = std::thread::Builder::new().name("pc-scratch-disks".into()).spawn(move || {
let found: Option<u64> = sysinfo::Disks::new_with_refreshed_list_specifics(sysinfo::DiskRefreshKind::nothing().with_storage()).ok().and_then(|disks| {
disks
.iter()
.filter(|d| dir.starts_with(d.mount_point()))
.max_by_key(|d| d.mount_point().as_os_str().len())
.filter(|d| volume_space(d.mount_point()) == Some((available, total)))
.map(|d| d.available_space())
});
LISTING.store(false, Ordering::Release);
let _ = tx.send(found);
});
if spawned.is_err() {
LISTING.store(false, Ordering::Release);
return available;
}
rx.recv_timeout(PURGEABLE_WAIT).ok().flatten().unwrap_or(available)
}
/// How long a measurement waits for the mounted-volume listing before using the `statvfs` figure.
#[cfg(target_os = "macos")]
const PURGEABLE_WAIT: Duration = Duration::from_millis(500);
#[cfg(all(any(unix, windows), not(target_os = "macos")))]
fn with_purgeable_space(_dir: &Path, available: u64, _total: u64) -> u64 {
available
}
#[cfg(not(any(unix, windows)))]
fn free_space(_dir: &Path) -> Option<(u64, u64)> {
None
}
/// Called after resident memory grew.
fn maybe_evict() {
let budget = M.budget.load(Ordering::Relaxed);
if budget == 0 {
// The supervisor retries when there is one; this can be any thread, the UI's too, and a
// retry waits for the folder.
if MAINTENANCE.load(Ordering::Acquire) == 0 {
M.retry();
}
return;
}
let resident = M.resident.load(Ordering::Relaxed);
if resident <= budget {
return;
}
let worker = MAINTENANCE.load(Ordering::Acquire) > 0;
// Far over budget (or no worker thread): this thread helps.
if !worker || resident > budget.saturating_add(budget / 4) {
M.sweep(low_water(budget), 1 << 16);
}
}
fn low_water(budget: usize) -> usize {
budget / 10 * 9
}
// The engine owns and joins the worker. Standalone raster consumers keep synchronous
// eviction; this crate never starts a background thread or retains its owner.
static MAINTENANCE: AtomicUsize = AtomicUsize::new(0);
/// Register an externally owned residency worker. Keep this guard until that worker exits.
pub struct Maintenance;
pub fn background_maintenance() -> Maintenance {
MAINTENANCE.fetch_add(1, Ordering::AcqRel);
Maintenance
}
impl Drop for Maintenance {
fn drop(&mut self) {
MAINTENANCE.fetch_sub(1, Ordering::AcqRel);
}
}
/// One bounded clock pass, plus a due retry of a paused scratch disk. The caller owns
/// scheduling and shutdown.
pub fn maintain_budget() -> usize {
M.retry();
let budget = M.budget.load(Ordering::Relaxed);
if budget == 0 || M.resident.load(Ordering::Relaxed) <= budget {
return 0;
}
M.sweep(low_water(budget), 4096)
}
/// Change the memory budget of a configured scratch disk (the memory limit moved). A paused
/// disk keeps its pause and resumes with this budget.
pub fn set_budget(budget_bytes: usize) {
let mut c = M.config();
if c.dir.is_none() || c.budget == 0 {
return;
}
c.budget = budget_bytes.max(1);
if c.paused.is_none() {
M.set_active(c.budget);
}
drop(c);
maybe_evict();
}
/// Limit how large the scratch file may grow (`None`: only the free-space reserve applies).
/// Reaching the limit pauses spilling like a full disk; changing it retries a paused disk now.
pub fn set_size_cap(cap: Option<u64>) {
let mut c = M.config();
if c.size_cap == cap {
return;
}
c.size_cap = cap;
store_limit(&c);
M.next_space_check.store(0, Ordering::Relaxed);
if c.paused.is_some() {
c.backoff = RETRY_FIRST;
M.retry_now(c);
}
}
/// Turn the scratch disk on (`dir` and a non-zero `budget_bytes`) or off. Tiles already on disk
/// stay readable either way. Changing the directory starts a new scratch file there; the old one
/// is deleted once its last tile is freed or changed. A directory that can't be used is kept and
/// retried with backoff (spilling stays paused meanwhile); the error is returned and reported.
/// Waits up to 2 s for the folder; a folder that doesn't answer counts as unusable until it does.
pub fn configure(dir: Option<&Path>, budget_bytes: usize) -> Result<(), String> {
let dir = dir.filter(|_| budget_bytes > 0).map(Path::to_path_buf);
let mut c = M.config();
let old = if dir != c.dir {
c.room = None;
c.file.take()
} else {
None
};
c.dir = dir.clone();
c.budget = if dir.is_some() { budget_bytes } else { 0 };
c.backoff = RETRY_FIRST;
c.paused = None;
c.last_error = None;
M.paused.store(false, Ordering::Release);
M.next_space_check.store(0, Ordering::Relaxed);
drop(c);
let start = Instant::now();
let closing = old.map(retire);
if let Some(dir) = &dir {
M.prepare(dir);
}
// One wait for the whole change: closing the old file gets what the new folder left over.
if let Some(closing) = closing {
closing.wait_until(start.checked_add(QUERY_WAIT).unwrap_or(start));
}
let c = M.config();
if c.dir != dir {
// A newer configure owns the state now.
return Ok(());
}
if c.paused.is_some() {
return Err(c.last_error.clone().unwrap_or_default());
}
M.set_active(c.budget);
drop(c);
maybe_evict();
Ok(())
}
/// Changes whenever spilling turns on or off, including a pause after a disk error and the
/// resume after it. Owners of memory caps that depend on [`enabled`] re-apply them on a change.
pub fn epoch() -> u64 {
M.epoch.load(Ordering::Acquire)
}
/// Whether spilling is paused after a scratch disk failure (it retries on its own).
pub fn paused() -> bool {
M.paused.load(Ordering::Acquire)
}
/// Retry a paused scratch disk on the next maintenance pass instead of after its backoff.
#[doc(hidden)]
pub fn retry_now_for_tests() {
if let Some(p) = &mut M.config().paused {
p.retry_at = Instant::now();
}
}
/// Where the tile memory stands.
#[derive(Clone, Debug, Default, PartialEq, Eq, serde::Serialize)]
#[serde(rename_all = "camelCase")]
pub struct SpillStats {
/// Pixel bytes of live tiles in memory.
pub resident_bytes: usize,
pub live_tiles: usize,
/// 0 = spilling off.
pub budget_bytes: usize,
pub dir: Option<PathBuf>,
/// Bytes allocated in the current scratch file.
pub scratch_bytes: u64,
pub evictions: u64,
pub reloads: u64,
/// Compressed bytes written to scratch so far.
pub written_bytes: u64,
pub last_error: Option<String>,
/// Spilling is paused after a scratch disk failure and will be retried.
pub paused: bool,
/// Scratch file size limit ([`set_size_cap`]); `None` = only the free-space reserve.
pub size_cap_bytes: Option<u64>,
/// Spilling is on but the scratch directory's volume won't report its free space ([`free_space_unmeasured`]).
pub free_space_unmeasured: bool,
}
pub fn stats() -> SpillStats {
let c = M.config();
SpillStats {
resident_bytes: M.resident.load(Ordering::Relaxed),
live_tiles: M.live.load(Ordering::Relaxed),
budget_bytes: M.budget.load(Ordering::Relaxed),
dir: c.dir.clone(),
scratch_bytes: c.file.as_ref().map_or(0, |f| f.used()),
evictions: M.evictions.load(Ordering::Relaxed),
reloads: M.reloads.load(Ordering::Relaxed),
written_bytes: M.written.load(Ordering::Relaxed),
last_error: c.last_error.clone(),
paused: c.paused.is_some(),
size_cap_bytes: c.size_cap,
free_space_unmeasured: enabled() && (M.space_unmeasured.load(Ordering::Relaxed) || query_overdue(c.dir.as_deref())),
}
}
/// Last storage error, without scanning the scratch allocator for UI status updates.
pub fn last_error() -> Option<String> {
M.config().last_error.clone()
}
/// Uncompressed tile bytes the scratch disk can still take before it reaches its size limit
/// ([`set_size_cap`]) or the volume's free-space reserve, so an import can admit tile pixels
/// beyond physical RAM. `None` while spilling is off or paused, and when neither the free space
/// nor a size limit is known (nothing to promise), which includes a folder that doesn't answer
/// within 2 s. Tiles are written compressed; this counts them uncompressed, less 1/64 for the allocator's block rounding, so it never over-promises.
pub fn scratch_capacity() -> Option<u64> {
if !enabled() || paused() {
return None;
}
let dir = M.config().dir.clone()?;
M.measure(&dir);
let c = M.config();
// A slow query must not describe a directory configured meanwhile, and a sweep can also have
// paused spilling meanwhile.
if c.dir.as_deref() != Some(dir.as_path()) || c.paused.is_some() {
return None;
}
let used = c.file.as_ref().map_or(0, |f| f.used());
let cap = c.size_cap;
let room = c.room.map(|room| room.saturating_sub(used));
drop(c);
let room = match (room, cap) {
(Some(room), Some(cap)) => room.min(cap.saturating_sub(used)),
(Some(room), None) => room,
(None, Some(cap)) => cap.saturating_sub(used),
(None, None) => return None,
};
Some(room - room / 64)
}
/// Whether spilling is on but the scratch directory's volume won't report its free space, so the
/// reserve doesn't apply and imports earn scratch room only up to a size limit. Two short locks,
/// neither ever held across a query, so it is safe to call every frame. A query past its wait
/// counts as unmeasured even with nobody waiting on it.
pub fn free_space_unmeasured() -> bool {
if !enabled() {
return false;
}
if M.space_unmeasured.load(Ordering::Relaxed) {
return true;
}
let c = M.config();
query_overdue(c.dir.as_deref())
}
/// Whether spilling is on (tiles beyond the budget go to disk).
pub fn enabled() -> bool {
M.budget.load(Ordering::Relaxed) > 0
}
/// Whether any live tile in the process is currently unreadable (cheap; the fast path of
/// every per-document health check).
pub fn any_failed() -> bool {
M.failed.load(Ordering::Acquire) > 0
}
/// Process-wide status for the UI: some live tile, in any document, is unreadable. Commit
/// guards check only the pixels they publish ([`Tile::scratch_health`](crate::Tile::scratch_health)
/// and the document's health) so one document's failure does not block the others.
pub fn check_integrity() -> Result<(), String> {
if any_failed() {
Err(M.config().last_error.clone().unwrap_or_else(|| "scratch pixels are unreadable; editing and saving are blocked".into()))
} else {
Ok(())
}
}
/// Capture before an edit/import/save or derived cache computation. A tile that fails or
/// recovers while the operation runs might have fed it placeholder pixels and then been
/// dropped or repaired; its result must still never be committed as real pixels. Both failure
/// and recovery change this generation. Tiles that were already unreadable when the operation
/// began do not change it: callers also check the health of the pixels they read.
pub fn read_error_generation() -> u64 {
M.read_errors.load(Ordering::Acquire)
}
/// Refuse a result if any tile failed or recovered since `generation` was captured. A retry
/// (capturing a new generation) succeeds once the transition is over.
pub fn check_since(generation: u64) -> Result<(), String> {
if generation == read_error_generation() {
Ok(())
} else {
Err(last_error().unwrap_or_else(|| "scratch read failed during this operation; the result was discarded".into()))
}
}
/// A second handle to the current scratch file, for tests that damage or restore its bytes.
/// The Unix file is unlinked, so it cannot be reopened by path. All scratch I/O is positioned,
/// so the shared file offset of a duplicated handle does not affect it.
#[doc(hidden)]
pub fn scratch_handle_for_tests() -> Option<std::fs::File> {
M.config().file.as_ref().and_then(|f| f.duplicate_handle().ok())
}
/// Runs at the start of every folder query, off every lock: tests stall it to simulate a dead mount.
#[doc(hidden)]
pub fn set_query_hook_for_tests(hook: Option<fn(&Path)>) {
*QUERY_HOOK.write().unwrap_or_else(PoisonError::into_inner) = hook;
}
/// Query threads still alive, so a test can wait until a stalled query has fully settled.
#[doc(hidden)]
pub fn query_threads_for_tests() -> usize {
QUERY_THREADS.load(Ordering::Acquire)
}
/// Evict down to the budget now, on this thread (tests, and before a measurement).
pub fn settle() {
let budget = M.budget.load(Ordering::Relaxed);
// Stops when nothing more can be evicted (every remaining tile is in use).
while budget > 0 && M.resident.load(Ordering::Relaxed) > budget {
if M.sweep(budget, usize::MAX) == 0 {
break;
}
}
}
fn log_error(msg: &str) {
#[cfg(not(target_arch = "wasm32"))]
eprintln!("photocraft: {msg}");
#[cfg(target_arch = "wasm32")]
let _ = msg;
}
#[cfg(test)]
mod tests {
use super::*;
#[cfg(windows)]
#[test]
fn free_space_keeps_a_trailing_dot_folder() {
let base = std::fs::canonicalize(std::env::temp_dir()).unwrap().join(format!("photocraft-dot-{}", std::process::id()));
let dir = base.join("x.");
if std::fs::create_dir_all(&dir).is_err() {
let _ = std::fs::remove_dir_all(&base);
return;
}
let space = free_space(&dir);
let _ = std::fs::remove_dir_all(&base);
assert!(space.is_some());
}
// `free_space` returned `None` on Windows before: `canonicalize` gives `\\?\C:\..`, which never
// started with the mount point `C:\`.
#[cfg(windows)]
#[test]
fn free_space_finds_the_temp_volume_on_windows() {
let temp = std::env::temp_dir();
let (available, total) = free_space(&temp).unwrap();
assert!(total > 0);
assert!(available <= total);
let mut temp_volume_total = 0;
winsafe::GetDiskFreeSpaceEx(Some(temp.to_str().unwrap()), None, Some(&mut temp_volume_total), None).unwrap();
assert_eq!(total, temp_volume_total);
}
// The real redirector path: the administrative share of this machine's system drive.
#[cfg(windows)]
#[test]
fn free_space_reads_a_unc_path() {
let unc = Path::new(r"\\localhost\C$\Windows");
if std::fs::canonicalize(unc).is_err() {
eprintln!("the administrative share {} isn't reachable; skipping", unc.display());
return;
}
let (_, unc_total) = free_space(unc).unwrap();
let (_, local_total) = free_space(Path::new(r"C:\")).unwrap();
assert_eq!(unc_total, local_total);
}
#[cfg(windows)]
#[test]
fn free_space_reads_a_folder_past_max_path() {
let base = std::fs::canonicalize(std::env::temp_dir()).unwrap().join(format!("photocraft-long-{}", std::process::id()));
let mut deep = base.clone();
while deep.as_os_str().len() <= 300 {
deep.push("a".repeat(40));
}
if std::fs::create_dir_all(&deep).is_err() {
let _ = std::fs::remove_dir_all(&base);
return;
}
let space = free_space(&deep);
let _ = std::fs::remove_dir_all(&base);
assert!(space.is_some());
}
#[cfg(windows)]
#[test]
fn free_space_reads_a_non_utf8_folder() {
use std::os::windows::ffi::OsStringExt;
let mut wide: Vec<u16> = format!("photocraft-nonutf8-{}-", std::process::id()).encode_utf16().collect();
wide.push(0xD800);
let dir = std::env::temp_dir().join(std::ffi::OsString::from_wide(&wide));
if std::fs::create_dir_all(&dir).is_err() {
return;
}
let space = free_space(&dir);
let _ = std::fs::remove_dir_all(&dir);
assert!(space.is_some());
}
// `/dev/shm` is tmpfs, which sysinfo never lists: the same situation as an unlisted NFS mount.
// Before the directory itself was asked, it reported the numbers of `/`.
#[cfg(target_os = "linux")]
#[test]
fn free_space_reads_an_unlisted_mount() {
let shm = Path::new("/dev/shm");
if !shm.is_dir() {
return;
}
let (available, total) = free_space(shm).unwrap();
assert!(available <= total);
// An independent oracle: `df` asks the same mount for its size.
let Ok(out) = std::process::Command::new("df").args(["-B1", "--output=size"]).arg(shm).output() else {
eprintln!("df couldn't be run; skipping the comparison");
return;
};
let text = String::from_utf8_lossy(&out.stdout);
let parsed = text.lines().rev().map(str::trim).find(|l| !l.is_empty()).and_then(|l| l.parse::<u64>().ok());
let Some(parsed) = parsed.filter(|_| out.status.success()) else {
eprintln!("df gave no size for {}; skipping the comparison", shm.display());
return;
};
assert_eq!(total, parsed);
}
#[cfg(target_os = "macos")]
#[test]
fn free_space_reads_the_temp_volume_on_macos() {
let temp = std::fs::canonicalize(std::env::temp_dir()).unwrap();
assert_eq!(free_space(&temp).unwrap().1, volume_space(&temp).unwrap().1);
}
#[cfg(target_os = "macos")]
#[test]
fn free_space_reads_an_unlisted_mount_on_macos() {
// `/dev` is devfs; a zero total counts as unknown, so compare only when it is known.
if let Some((_, total)) = free_space(Path::new("/dev")) {
assert_ne!(total, free_space(Path::new("/")).unwrap().1);
}
}
#[cfg(any(unix, windows))]
#[test]
fn free_space_of_a_missing_directory_is_unknown() {
let missing = std::env::temp_dir().join(format!("photocraft-missing-{}", std::process::id()));
assert_eq!(free_space(&missing), None);
}
#[cfg(any(unix, windows))]
#[test]
fn a_volume_with_no_total_is_unknown() {
assert_eq!(known_space(0, 0), None);
assert_eq!(known_space(5, 0), None);
assert_eq!(known_space(0, 10), Some((0, 10)));
assert_eq!(known_space(5, 10), Some((5, 10)));
}
static CAPPED_GATE: (Mutex<bool>, Condvar) = (Mutex::new(false), Condvar::new());
fn hold_capped(dir: &Path) {
if dir.file_name().and_then(|n| n.to_str()).is_some_and(|n| n.starts_with("photocraft-capped-")) {
let mut open = CAPPED_GATE.0.lock().unwrap_or_else(PoisonError::into_inner);
while !*open {
open = CAPPED_GATE.1.wait(open).unwrap_or_else(PoisonError::into_inner);
}
}
}
#[test]
fn query_threads_stay_capped_and_single_flight() {
set_query_hook_for_tests(Some(hold_capped));
let base = std::env::temp_dir().join(format!("photocraft-capped-{}", std::process::id()));
let first = start_query(&base, false).unwrap();
let again = start_query(&base, false).unwrap();
assert!(Arc::ptr_eq(&first.0, &again.0) && first.1 == again.1, "the same question must not start a second thread");
let mut started = 1;
for i in 0..2 * MAX_QUERIES {
if start_query(&base.join(format!("photocraft-capped-{i}")), false).is_some() {
started += 1;
}
}
assert_eq!(started, MAX_QUERIES);
// Exercise the real growth path while every query slot is occupied. A separate manager
// keeps this check independent of other tests' process-wide scratch configuration.
let file = ScratchFile::create(&base).unwrap();
let manager = Manager {
failed: AtomicUsize::new(0),
read_errors: AtomicU64::new(0),
resident: AtomicUsize::new(0),
live: AtomicUsize::new(0),
budget: AtomicUsize::new(1),
paused: AtomicBool::new(false),
epoch: AtomicU64::new(0),
space_limit: AtomicU64::new(u64::MAX),
next_space_check: AtomicU64::new(0),
recovering: AtomicBool::new(false),
space_unmeasured: AtomicBool::new(false),
registry: Mutex::new(Registry { cells: Vec::new(), hand: 0 }),
config: Mutex::new(Config {
dir: Some(base.join("growth")),
file: None,
last_error: None,
budget: 1,
paused: None,
backoff: RETRY_FIRST,
size_cap: None,
room: None,
}),
evictions: AtomicU64::new(0),
reloads: AtomicU64::new(0),
written: AtomicU64::new(0),
};
let allowed = manager.has_room(&file);
let next_check = manager.next_space_check.load(Ordering::Relaxed);
let unmeasured = manager.space_unmeasured.load(Ordering::Relaxed);
*CAPPED_GATE.0.lock().unwrap_or_else(PoisonError::into_inner) = true;
CAPPED_GATE.1.notify_all();
let start = Instant::now();
while query_threads_for_tests() != 0 {
assert!(start.elapsed() < Duration::from_secs(30), "queries never finished");
std::thread::sleep(Duration::from_millis(10));
}
set_query_hook_for_tests(None);
assert!(allowed, "the last measured growth limit still applies");
assert_eq!(next_check, 0, "a rejected growth query must stay due");
assert!(unmeasured, "a rejected growth query must not report the old measurement as current");
drop(file);
let _ = std::fs::remove_dir_all(&base);
}
#[test]
fn failed_read_retains_backing_and_blocks_commit_until_repaired() {
let dir = std::env::temp_dir().join(format!("photocraft-read-failure-{}", std::process::id()));
let file = Arc::new(ScratchFile::create(&dir).unwrap());
let mut tile = crate::Tile { cell: Cell::new(vec![73; 1024]) };
let generation = read_error_generation();
assert_eq!(tile.cell.evict(&file).unwrap(), 1024);
let good = tile.cell.slot.lock().unwrap().as_ref().unwrap().1;
tile.cell.slot.lock().unwrap().as_mut().unwrap().1.crc32 ^= 1;
assert!(tile.try_bytes().is_err());
let failed_generation = read_error_generation();
assert!(tile.cell.data.read().unwrap().is_none(), "placeholder must never become stored pixels");
assert!(check_integrity().is_err());
assert!(tile.scratch_health().is_err(), "the tile reports its own failure");
assert!(crate::Tile::from_vec(vec![1; 16]).scratch_health().is_ok(), "other tiles stay healthy");
assert!(tile.try_bytes().is_err());
assert!(check_since(failed_generation).is_ok(), "re-reading a tile that already failed is not a new transition");
tile.bytes_mut()[0] = 9;
assert!(tile.cell.data.read().unwrap().is_none());
assert!(tile.cell.slot.lock().unwrap().is_some(), "a failed mutation must preserve the original extent");
let snapshot = tile.clone();
assert!(Arc::ptr_eq(&tile.cell, &snapshot.cell));
configure(None, 0).unwrap();
assert!(check_integrity().is_err(), "changing preferences must not clear unreadable pixels");
tile.cell.slot.lock().unwrap().as_mut().unwrap().1 = good;
assert_eq!(&*tile.try_bytes().unwrap(), &[73; 1024]);
assert!(check_integrity().is_ok());
assert!(tile.scratch_health().is_ok());
assert!(check_since(generation).is_err(), "repairing or dropping a failed tile must not validate an earlier result");
assert!(check_since(failed_generation).is_err(), "recovery must reject a computation begun during the failure");
assert_eq!(tile.cell.evict(&file).unwrap(), 1024);
tile.cell.slot.lock().unwrap().as_mut().unwrap().1.crc32 ^= 1;
assert!(tile.try_bytes().is_err());
let dropped_generation = read_error_generation();
drop((snapshot, tile, file));
assert!(check_integrity().is_ok());
assert!(check_since(dropped_generation).is_err(), "dropping the failed tile must also reject its placeholder result");
let _ = std::fs::remove_dir(&dir);
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.