Files
photocraft/crates/io/src/memory.rs
T
Khawar Zamman Wani 20c0d65342 PSD admission: no free-memory advice when the platform cap also binds
Where the 32-bit cap equals the measured room, more free memory can't raise the
limit, so the refusal shouldn't tell the user to close other apps.
2026-11-06 18:01:16 +05:30

1367 lines
68 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! How much memory this process can still use, so an import too large for the machine is
//! refused with an error instead of ending the app. Linux overcommits: an allocation that can't
//! be backed still succeeds, and the out-of-memory killer ends the process (and every open
//! document) when its pages are written, so a fallible allocation alone never fails there.
use crate::IoError;
/// Memory left free beside what an import needs: for the app, its display and the system.
pub const RESERVE: u64 = 512 << 20;
/// Automatic allowance for native platforms when available memory is unknown.
///
/// Estimates above it need explicit per-invocation approval, up to the platform's aggregate
/// admission limit (see [`native_platform_cap`]). This is a conservative automatic admission
/// threshold, not a hard ceiling and not a per-buffer allocation bound.
pub const NATIVE_FALLBACK_BUDGET: u64 = 2 << 30;
/// Automatic allowance for WebAssembly execution.
///
/// Estimates above it need explicit per-invocation approval, up to
/// [`WASM_MAX_PEAK_BUDGET`]. This is a conservative product threshold, not an assertion that
/// the browser can allocate that much.
pub const WASM_BUDGET: u64 = 1 << 30;
/// Upper ceiling on the automatic soft import budget when available memory is known.
pub const MAX_SOFT_BUDGET: u64 = 8 << 30;
/// Estimate above which an import made with unknown available memory carries an extra warning.
///
/// It is a warning threshold, not a hard ceiling: explicit approval remains possible up to the
/// platform's actual allocation limits, but the process may run out of memory.
pub const UNKNOWN_MEMORY_WARNING_THRESHOLD: u64 = 8 << 30;
/// Largest reserve subtracted from commit headroom when known. The reserve is a quarter of the
/// headroom, at least [`LOW_MEMORY_RESERVE`] and at most this, so a machine with little commit
/// headroom still has room for a small file.
pub const COMMIT_RESERVE: u64 = 512 << 20;
/// The smallest amount an approved import leaves free: for the app, its display and the system.
///
/// Free RAM or commit headroom at or below it leaves no room at all, so every file is refused.
pub const LOW_MEMORY_RESERVE: u64 = 256 << 20;
/// What automatic opening leaves free once that is less than the quarter-of-free-RAM rule.
const AUTOMATIC_RAM_RESERVE: u64 = 1 << 30;
/// When opening a file would leave less than this free, the approval prompt warns that
/// PhotoCraft may run out of memory.
pub const LOW_MEMORY_WARNING_MARGIN: u64 = 1 << 30;
/// Bytes Rust's layout rules allow for one contiguous allocation on this target
/// (`isize::MAX`), not a bound on an import's aggregate peak.
///
/// A layer plane, a decode buffer or a tile is one contiguous allocation, so each must fit this
/// limit at the point it is allocated. An import's peak is the *sum* of many such buffers and
/// may legitimately exceed this; decode paths enforce their own per-buffer limits
/// (`photocraft-psd::MAX_DECODED_BYTES`, `photocraft-codecs`' `Limits::max_alloc`) there.
pub const MAX_SINGLE_ALLOCATION: u64 = isize::MAX as u64;
/// Architectural maximum linear memory of wasm32: 65,536 pages of 64 KiB (4 GiB).
///
/// This is the whole address space of one wasm32 instance, shared with the resident document,
/// history, decoder buffers, the allocator, the stack and the runtime. It is an address-space
/// bound, not a promise that 4 GiB can be allocated; browsers may cap linear memory lower.
pub const WASM_LINEAR_MEMORY_LIMIT: u64 = 4u64 << 30;
/// Largest single Rust allocation on wasm32 (`isize::MAX`): 2 GiB - 1.
///
/// A per-buffer bound only. Aggregate admission on web uses [`WASM_MAX_PEAK_BUDGET`]; the layout
/// limit itself rejects a larger single buffer, and decoders may apply a tighter cap.
pub const WASM_MAX_SINGLE_ALLOCATION: u64 = (1u64 << 31) - 1;
/// Conservative product cap for the aggregate peak of one web import: 2 GiB.
///
/// Chosen by this project, not dictated by the architecture: it sits below both the 4 GiB
/// wasm32 linear-memory limit (leaving room for the runtime, stack, allocator metadata and the
/// resident document) and is reachable only through explicit approval above [`WASM_BUDGET`].
/// Browsers commonly allow less, and allocation may still fail. Do not read it as a guarantee.
pub const WASM_MAX_PEAK_BUDGET: u64 = 2 << 30;
/// Conservative product cap for the aggregate peak of a 32-bit native process: 2 GiB.
///
/// A 32-bit process has a 4 GiB address space, but the kernel/reserved range, runtime, stack,
/// allocator metadata, document and history share it. This is a product choice well below the
/// architectural limit, not an architectural bound.
pub const NATIVE_32BIT_PEAK_CAP: u64 = 2 << 30;
/// A snapshot of system memory availability, distinguishing physical RAM from swap and commit headroom.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub struct MemorySnapshot {
/// Currently available physical RAM (A) in bytes, bounded by applicable container or process limits.
/// Free swap is explicitly excluded. A value of `Some(0)` represents zero capacity, not unknown memory.
pub available_ram: Option<u64>,
/// Available swap headroom in bytes, if known.
pub swap_free: Option<u64>,
/// System or process commit headroom (C) in bytes, if measurable.
pub commit_headroom: Option<u64>,
}
#[cfg(any(test, feature = "testgen"))]
thread_local! {
static MOCK_SNAPSHOT: std::cell::RefCell<Option<MemorySnapshot>> = const { std::cell::RefCell::new(None) };
/// A per-attempt provider consulted on every query, unlike the fixed [`MOCK_SNAPSHOT`].
/// Tests use it to change the measured capacity between admission checks from another
/// thread; it is thread-local, so it never affects unrelated parallel tests.
static MOCK_PROVIDER: std::cell::RefCell<Option<std::rc::Rc<dyn Fn() -> MemorySnapshot>>> = const { std::cell::RefCell::new(None) };
/// Mocked [`scratch_capacity`]: `Some(None)` = spilling off, `Some(Some(n))` = `n` bytes.
static MOCK_SCRATCH: std::cell::Cell<Option<Option<u64>>> = const { std::cell::Cell::new(None) };
}
/// Tile bytes the scratch disk can take beyond RAM: `None` while spilling is off, paused or
/// unavailable (web), or its room is unknown. See [`photocraft_raster::spill::scratch_capacity`].
///
/// Test builds: a mocked memory snapshot without a mocked scratch disk measures no scratch, so a
/// test that mocks RAM keeps the RAM-only policy whatever another test did to the process-wide
/// scratch disk.
pub fn scratch_capacity() -> Option<u64> {
#[cfg(any(test, feature = "testgen"))]
{
if let Some(mock) = MOCK_SCRATCH.with(std::cell::Cell::get) {
return mock;
}
if MOCK_SNAPSHOT.with(|m| m.borrow().is_some()) || MOCK_PROVIDER.with(|p| p.borrow().is_some()) {
return None;
}
}
if cfg!(target_arch = "wasm32") {
return None;
}
photocraft_raster::spill::scratch_capacity()
}
/// How much of `spillable` tile bytes the scratch disk covers on `platform` right now. The web
/// has no scratch disk, so it never gets credit.
fn scratch_credit_for(platform: Platform, spillable: u64) -> u64 {
if platform == Platform::Web || spillable == 0 {
return 0;
}
scratch_capacity().map_or(0, |room| spillable.min(room))
}
/// [`scratch_credit_for`] on this build's platform.
pub(crate) fn scratch_credit(spillable: u64) -> u64 {
scratch_credit_for(active_platform(), spillable)
}
impl MemorySnapshot {
/// Unknown memory measurement.
pub const UNKNOWN: Self = Self { available_ram: None, swap_free: None, commit_headroom: None };
/// The current measurement from the shared detector, [`photocraft_raster::memory::system`],
/// which also sizes the tile residency budget.
pub fn current() -> Self {
#[cfg(any(test, feature = "testgen"))]
{
if let Some(provider) = MOCK_PROVIDER.with(|p| p.borrow().clone()) {
return provider();
}
if let Some(mock) = MOCK_SNAPSHOT.with(|m| *m.borrow()) {
return mock;
}
}
photocraft_raster::memory::system::current().into()
}
}
impl From<photocraft_raster::memory::system::SystemMemory> for MemorySnapshot {
/// The shared detector's measurement; an unreadable constraint is already the fail-closed
/// `Some(0)` available RAM, which admission refuses.
fn from(m: photocraft_raster::memory::system::SystemMemory) -> Self {
Self { available_ram: m.available_ram, swap_free: m.swap_free, commit_headroom: m.commit_headroom }
}
}
/// Resolved memory budgets derived from a [`MemorySnapshot`].
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct MemoryBudget {
/// Automatic admission ceiling (S): imports requiring <= S open without confirmation.
pub soft_limit: u64,
/// Hard refusal ceiling (H): imports requiring > H are refused and cannot be overridden.
pub hard_limit: u64,
/// Currently available physical RAM from the snapshot, if known.
pub available_ram: Option<u64>,
/// Set when available memory is unknown: estimates above this threshold still need explicit
/// approval but also carry the uncertain-capacity warning. `None` when capacity is known.
pub warning_threshold: Option<u64>,
/// The free memory measured when measured memory is what set the hard limit: the smaller of
/// the known available RAM and commit headroom. `None` when neither is known, when the
/// platform cap or the caller's limit is what bound the hard limit, and on the web. A refusal
/// reports it so the user can be told to free memory (see [`low_memory_advice`]).
pub measured_free: Option<u64>,
}
/// Admission decision for a given required memory estimate.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum BudgetDecision {
/// Estimated memory <= soft limit: open automatically.
Automatic,
/// Soft limit < estimated memory <= hard limit: requires explicit user/caller confirmation.
RequiresApproval,
/// Estimated memory > hard limit, or the saturated `u64::MAX` overflow sentinel: refused.
Refused,
}
impl MemoryBudget {
/// Determines the admission decision for an estimated requirement in bytes.
///
/// `u64::MAX` is the sentinel a format estimate produces when a size overflowed `u64`
/// (`photocraft-io`'s TIFF estimates saturate there rather than wrap). It is not a real
/// requirement, so it is always refused, even when the hard limit is itself `u64::MAX` (the
/// native unknown-memory cap) and even with explicit approval or a matching one-shot
/// estimate. The refusal keeps the estimate and limit as they are; no value is invented.
pub fn decide(&self, required: u64) -> BudgetDecision {
if required == u64::MAX {
return BudgetDecision::Refused;
}
if required <= self.soft_limit {
BudgetDecision::Automatic
} else if required <= self.hard_limit {
BudgetDecision::RequiresApproval
} else {
BudgetDecision::Refused
}
}
/// Whether an approvable estimate also needs the uncertain-capacity warning.
///
/// This is only meaningful together with [`BudgetDecision::RequiresApproval`]; it says the
/// budget came from the unknown-memory fallback and the estimate is above
/// [`UNKNOWN_MEMORY_WARNING_THRESHOLD`].
pub fn requires_uncertainty_warning(&self, required: u64) -> bool {
self.warning_threshold.is_some_and(|threshold| required > threshold)
}
/// The free memory to report when `required` is refused, or `None` when closing other apps
/// cannot help: the estimate overflowed `u64` (`u64::MAX`), or the limit that refused it was
/// not set by measured memory.
pub fn refusal_free_memory(&self, required: u64) -> Option<u64> {
if required == u64::MAX { None } else { self.measured_free }
}
}
/// The sentence appended to a hard-memory refusal when measured free memory set the limit; empty
/// for `None`. `Some(0)` also covers the fail-closed reading of an unreadable memory limit.
pub fn low_memory_advice(free_memory: &Option<u64>) -> String {
match free_memory {
None => String::new(),
Some(0) => ". PhotoCraft measured no free memory, or could not read this system's memory limit. Close other apps and try again".to_string(),
Some(n) => format!(". About {} of memory is free. Close other apps and try again", size_text(*n)),
}
}
/// A size for people: "3.0 GiB", "900 MiB", "512 B".
fn size_text(bytes: u64) -> String {
if bytes >= 1 << 30 {
format!("{:.1} GiB", bytes as f64 / (1u64 << 30) as f64)
} else if bytes >= 1 << 20 {
format!("{} MiB", bytes / (1 << 20))
} else {
format!("{bytes} B")
}
}
/// Whether an approval-required estimate carries the unknown-capacity warning, given the
/// capacity measured when the estimate was made.
///
/// A known capacity never carries it (a measured number is reported instead of a guess); when
/// capacity is unknown, an estimate above [`UNKNOWN_MEMORY_WARNING_THRESHOLD`] is still
/// approvable but says the process or tab may run out of memory. Kept separate from
/// [`MemoryBudget`] so a pending approval can carry the flag across a later, fresh measurement.
pub fn uncertain_capacity_warning(required: u64, available_ram: Option<u64>) -> bool {
available_ram.is_none() && required > UNKNOWN_MEMORY_WARNING_THRESHOLD
}
/// Which platform policy to resolve. Tests use this to exercise the web policy on any host.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Platform {
Native,
Web,
}
/// The platform policy selected for this build: Web on wasm32, Native everywhere else.
fn active_platform() -> Platform {
if cfg!(target_arch = "wasm32") { Platform::Web } else { Platform::Native }
}
/// Aggregate address-space bound for native admission (not a per-buffer allocation bound).
///
/// A 64-bit process has no practical aggregate address-space limit measurable through safe
/// standard APIs, so this is `u64::MAX`; per-buffer and format limits are enforced where buffers
/// are actually allocated. A 32-bit process uses [`NATIVE_32BIT_PEAK_CAP`].
pub fn native_platform_cap() -> u64 {
if cfg!(target_pointer_width = "32") { NATIVE_32BIT_PEAK_CAP } else { u64::MAX }
}
/// Resolves the adaptive hard and soft import budgets from a snapshot and an optional caller limit.
///
/// The limits are for an import's aggregate peak estimate, not for one allocation: a peak may sum
/// many buffers, each of which is separately bounded where the decoder allocates it.
///
/// Policy (A = available RAM, C = commit headroom, each when known):
/// - Known RAM: H = min(floor(3*A/4), A - [`LOW_MEMORY_RESERVE`], C - reserve if known,
/// [`native_platform_cap`]), where the commit reserve is a quarter of C, at least
/// [`LOW_MEMORY_RESERVE`] and at most [`COMMIT_RESERVE`]. S = min(A/2, 8 GiB, max(A - 1 GiB,
/// A/4), max(C - [`COMMIT_RESERVE`], C/4) if known, H). Above 4/3 GiB free this is the usual
/// "leave 1 GiB free"; below it up to a quarter of free RAM opens automatically and the rest
/// goes to approval. At or below [`LOW_MEMORY_RESERVE`] of either there is no room.
/// - Unknown native RAM: S = min(2 GiB, commit soft room if known, H) where H is
/// [`native_platform_cap`], reduced by known commit headroom as above; approval above S is
/// possible up to H. 8 GiB is a warning threshold, not H.
/// - <= S: automatic; S < E <= H: explicit approval; > H: refuse, no unlimited override.
/// - The saturated `u64::MAX` overflow sentinel is always refused, even when H is `u64::MAX`
/// (see [`MemoryBudget::decide`]).
/// - Known zero available RAM stays zero (it never becomes unknown/free). The fail-closed reading
/// of an unreadable memory limit is `Some(0)`, so it stays refused; only a credited tile share
/// (see [`resolve_budget_with_scratch`]) can pass, as before.
/// - swap is never part of the adaptive budget.
/// - Explicit caller limits may lower admission, never bypass the hard boundary.
pub fn resolve_budget(snapshot: MemorySnapshot, caller_limit: Option<u64>) -> MemoryBudget {
resolve_budget_for(active_platform(), snapshot, caller_limit)
}
/// [`resolve_budget`] for an import whose estimate includes `spillable` bytes of tile pixels.
///
/// While the scratch disk is spilling (on and not paused), tiles beyond the residency budget are
/// written to it, so those pixels are not bounded by physical RAM: the part of `spillable` the
/// disk has room for ([`scratch_capacity`], after the Scratch Size Limit and the free-space
/// reserve) is added to both S and H before the caller's explicit limit applies. Equivalently,
/// the non-spillable working memory (decode buffers, conversion copies, merged planes) is
/// admitted against the RAM policy alone, and the whole estimate against RAM plus scratch room.
/// With spilling off or paused, and always on the web, this is exactly [`resolve_budget`].
pub fn resolve_budget_with_scratch(snapshot: MemorySnapshot, caller_limit: Option<u64>, spillable: u64) -> MemoryBudget {
let platform = active_platform();
resolve_budget_credited(platform, snapshot, caller_limit, scratch_credit_for(platform, spillable))
}
/// [`resolve_budget`] for an explicit platform, so tests can exercise the web policy on a native host.
fn resolve_budget_for(platform: Platform, snapshot: MemorySnapshot, caller_limit: Option<u64>) -> MemoryBudget {
resolve_budget_credited(platform, snapshot, caller_limit, 0)
}
/// The policy with `credit` bytes of scratch room added to S and H before the caller's limit.
fn resolve_budget_credited(platform: Platform, snapshot: MemorySnapshot, caller_limit: Option<u64>, credit: u64) -> MemoryBudget {
if platform == Platform::Web {
let mut hard = WASM_MAX_PEAK_BUDGET;
if let Some(caller) = caller_limit.filter(|&c| c > 0) {
hard = hard.min(caller);
}
return MemoryBudget { soft_limit: WASM_BUDGET.min(hard), hard_limit: hard, available_ram: None, warning_threshold: None, measured_free: None };
}
let platform_cap = native_platform_cap();
let ram = snapshot.available_ram;
let commit = snapshot.commit_headroom;
// The room measured memory leaves; with neither measurement known only the platform cap bounds.
let measured_room = match (ram.map(ram_hard_room), commit.map(commit_hard_room)) {
(Some(r), Some(c)) => Some(r.min(c)),
(r, c) => r.or(c),
};
let mut hard = measured_room.map_or(platform_cap, |room| room.min(platform_cap));
let commit_soft = commit.map(commit_soft_room);
let (mut soft, warning_threshold) = match ram {
Some(a) => (ram_soft_room(a).min(commit_soft.unwrap_or(u64::MAX)).min(hard), None),
None => (NATIVE_FALLBACK_BUDGET.min(commit_soft.unwrap_or(u64::MAX)).min(hard), Some(UNKNOWN_MEMORY_WARNING_THRESHOLD)),
};
// Tile pixels the scratch disk takes need no RAM (see [`resolve_budget_with_scratch`]).
hard = hard.saturating_add(credit);
soft = soft.saturating_add(credit);
let machine_limit = hard;
if let Some(caller) = caller_limit.filter(|&c| c > 0) {
hard = hard.min(caller);
soft = soft.min(hard);
}
// Report the measured free memory only when it alone set the hard limit: where the platform
// cap equals the measured room, more free memory could not raise the limit.
let measured_free = match (ram, commit) {
(None, None) => None,
(Some(a), None) => Some(a),
(None, Some(c)) => Some(c),
(Some(a), Some(c)) => Some(a.min(c)),
}
.filter(|_| measured_room.is_some_and(|room| room < platform_cap) && hard >= machine_limit);
MemoryBudget { soft_limit: soft, hard_limit: hard, available_ram: ram, warning_threshold, measured_free }
}
/// Hard room (what an approved import may use) when `a` bytes of RAM are free: three quarters of
/// it, leaving at least [`LOW_MEMORY_RESERVE`].
fn ram_hard_room(a: u64) -> u64 {
let quarter_rule = ((a as u128 * 3) / 4) as u64;
quarter_rule.min(a.saturating_sub(LOW_MEMORY_RESERVE))
}
/// Automatic room when `a` bytes of RAM are free: half of it, up to [`MAX_SOFT_BUDGET`], leaving
/// 1 GiB free or, when that is less, a quarter of it.
fn ram_soft_room(a: u64) -> u64 {
(a / 2).min(MAX_SOFT_BUDGET).min(a.saturating_sub(AUTOMATIC_RAM_RESERVE).max(a / 4))
}
/// Hard room when `c` bytes of commit headroom remain: all but a reserve of a quarter, at least
/// [`LOW_MEMORY_RESERVE`] and at most [`COMMIT_RESERVE`].
fn commit_hard_room(c: u64) -> u64 {
// `clamp` panics only if its bounds are out of order, and they are constants.
const { assert!(LOW_MEMORY_RESERVE <= COMMIT_RESERVE) };
let reserve = (c / 4).clamp(LOW_MEMORY_RESERVE, COMMIT_RESERVE);
c.saturating_sub(reserve)
}
/// Automatic room when `c` bytes of commit headroom remain.
fn commit_soft_room(c: u64) -> u64 {
c.saturating_sub(COMMIT_RESERVE).max(c / 4)
}
/// Result of evaluating an import admission request.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct AdmissionOutcome {
pub budget: MemoryBudget,
/// Total authorized memory allowance for the entire attempt (top-level + nested decodes):
/// `min(S if automatic else H if approved, caller cap if any, approved_estimate if present)`.
pub authorized_total: u64,
}
/// Central evaluation of PSD admission against adaptive budgets and options.
///
/// Refuses before decoding if:
/// - `required` is the saturated `u64::MAX` overflow sentinel (see [`MemoryBudget::decide`]);
/// - `required > hard_limit` (regardless of approvals: hard ceiling cannot be overridden);
/// - `required > soft_limit` and high memory is not approved;
/// - high memory is approved, but `approved_estimate` is specified and `required > approved_estimate`
/// (preventing unbounded approval for altered/enlarged files).
///
/// `spillable` is the part of `required` that is tile pixels; while the scratch disk is spilling
/// the limits include the room it has for them (see [`resolve_budget_with_scratch`]). Errors
/// still report the whole `required` (the figure approval binds to) and the effective limits.
pub(crate) fn evaluate_psd_admission(
required: u64,
spillable: u64,
caller_limit: u64,
high_memory_approved: bool,
approved_estimate: Option<u64>,
snapshot: MemorySnapshot,
) -> Result<AdmissionOutcome, IoError> {
evaluate_psd_admission_for(active_platform(), required, spillable, caller_limit, high_memory_approved, approved_estimate, snapshot)
}
/// [`evaluate_psd_admission`] for an explicit platform, so tests can exercise the web policy on a native host.
fn evaluate_psd_admission_for(
platform: Platform,
required: u64,
spillable: u64,
caller_limit: u64,
high_memory_approved: bool,
approved_estimate: Option<u64>,
snapshot: MemorySnapshot,
) -> Result<AdmissionOutcome, IoError> {
let limit_opt = (caller_limit > 0).then_some(caller_limit);
let budget = resolve_budget_credited(platform, snapshot, limit_opt, scratch_credit_for(platform, spillable.min(required)));
let authorized_total = match budget.decide(required) {
BudgetDecision::Automatic => {
let mut cap = budget.soft_limit;
if let Some(caller) = limit_opt {
cap = cap.min(caller);
}
if let Some(appr) = approved_estimate {
cap = cap.min(appr);
}
cap
}
BudgetDecision::RequiresApproval => {
if !high_memory_approved {
return Err(IoError::PsdApprovalRequired {
required,
soft_limit: budget.soft_limit,
hard_limit: budget.hard_limit,
available_ram: budget.available_ram,
});
}
let mut cap = budget.hard_limit;
if let Some(caller) = limit_opt {
cap = cap.min(caller);
}
if let Some(appr) = approved_estimate {
cap = cap.min(appr);
}
cap
}
BudgetDecision::Refused => {
return Err(IoError::PsdImportBudget { required, limit: budget.hard_limit, free_memory: budget.refusal_free_memory(required) });
}
};
if required > authorized_total {
return Err(IoError::PsdApprovalRequired {
required,
soft_limit: budget.soft_limit,
hard_limit: budget.hard_limit,
available_ram: budget.available_ram,
});
}
Ok(AdmissionOutcome { budget, authorized_total })
}
/// Applies a caller's explicit local bounds to a nested decode.
///
/// A nested import spends the enclosing attempt's remaining allowance: it never resolves an
/// independent adaptive budget and never resets the parent's. The caller's explicit bounds still
/// apply, because they limit this attempt rather than describe a second budget:
/// `caller_limit > 0` is the lower caller allowance, and `approved_estimate` (when present) is the
/// estimate one-shot consent was given for. Both are checked before the parent is charged, so a
/// refusal leaves its remaining allowance untouched, and the tighter bound is the one reported.
///
/// A nested attempt cannot ask for fresh consent, so exceeding either bound is a hard refusal
/// ([`IoError::PsdImportBudget`], the form the outer caller limit already uses) rather than a new
/// approval request.
///
/// The saturated `u64::MAX` overflow sentinel is not covered here (there is no meaningful limit to
/// report when no local bound is set); [`crate::psd_gate::consume_attempt_allowance`] refuses it
/// before the parent is charged.
pub(crate) fn nested_import_local_bound(required: u64, caller_limit: u64, approved_estimate: Option<u64>) -> Result<(), IoError> {
let caller = (caller_limit > 0).then_some(caller_limit);
let limit = match (caller, approved_estimate) {
(Some(caller), Some(approved)) => Some(caller.min(approved)),
(caller, approved) => caller.or(approved),
};
match limit {
Some(limit) if required > limit => Err(IoError::PsdImportBudget { required, limit, free_memory: None }),
_ => Ok(()),
}
}
/// Bytes this process can still use without running out, or `None` where that isn't known. On
/// Linux: the free RAM the kernel can hand out (`MemAvailable`, capped by the process's memory
/// cgroup — v2 `memory.max` or v1 `memory.limit_in_bytes`/`memsw` — and those above it) plus free
/// swap (capped by the cgroup's swap limits). Elsewhere `None`: Windows refuses an allocation past
/// its commit limit, which the importers already report as an error, and macOS pages to disk as it
/// needs. macOS's physical-memory provider feeds the adaptive budget, not this legacy
/// RAM-plus-swap helper; flat and layered TIFF conversion keep their existing behaviour. Measured
/// by [`photocraft_raster::memory::system::available_with_swap`].
pub fn available() -> Option<u64> {
photocraft_raster::memory::system::available_with_swap()
}
/// Refuses to open a `w` × `h` px image whose layer and decode buffers take `needed` bytes when
/// `available` bytes (see [`available`]) can't hold them with [`RESERVE`] to spare.
pub(crate) fn check_fits(w: u32, h: u32, needed: u64, available: Option<u64>) -> Result<(), IoError> {
let Some(available) = available else { return Ok(()) };
if needed.checked_add(RESERVE).is_some_and(|n| n <= available) {
return Ok(());
}
let gb = |b: u64| b as f64 / 1e9;
Err(IoError::Unsupported(format!(
"not enough memory to open this {w} × {h} px image: it needs about {:.1} GB and {:.1} GB is free",
gb(needed),
gb(available)
)))
}
/// Sets a thread-local mock memory snapshot for testing policy and import admission.
#[cfg(any(test, feature = "testgen"))]
pub fn set_mock_memory(snapshot: Option<MemorySnapshot>) {
MOCK_SNAPSHOT.with(|m| *m.borrow_mut() = snapshot);
}
/// Runs a closure with a temporarily injected mock memory snapshot on the current thread.
///
/// Restores the previous snapshot upon return or panic, supporting nested invocations.
#[cfg(any(test, feature = "testgen"))]
pub fn with_mock_memory<R>(snapshot: MemorySnapshot, f: impl FnOnce() -> R) -> R {
let prev = MOCK_SNAPSHOT.with(|m| {
let old = *m.borrow();
*m.borrow_mut() = Some(snapshot);
old
});
struct Reset {
prev: Option<MemorySnapshot>,
}
impl Drop for Reset {
fn drop(&mut self) {
MOCK_SNAPSHOT.with(|m| *m.borrow_mut() = self.prev);
}
}
let _reset = Reset { prev };
f()
}
/// Runs a closure with a per-attempt memory provider on the current thread.
///
/// Unlike [`with_mock_memory`], the provider is consulted for every
/// [`MemorySnapshot::current`], so a test can change the measured capacity while an import is
/// waiting on the decode gate and observe the post-gate recheck. The provider is thread-local
/// and restored on return or panic, so it never overrides another test's measurement.
#[cfg(any(test, feature = "testgen"))]
pub fn with_mock_memory_provider<R>(provider: std::rc::Rc<dyn Fn() -> MemorySnapshot>, f: impl FnOnce() -> R) -> R {
let prev = MOCK_PROVIDER.with(|p| p.borrow_mut().replace(provider));
struct Reset {
prev: Option<std::rc::Rc<dyn Fn() -> MemorySnapshot>>,
}
impl Drop for Reset {
fn drop(&mut self) {
MOCK_PROVIDER.with(|p| *p.borrow_mut() = self.prev.take());
}
}
let _reset = Reset { prev };
f()
}
/// Runs a closure with a mocked scratch disk on the current thread: `Some(n)` = spilling with
/// `n` bytes of room, `None` = spilling off or paused. Restored on return or panic, and captured
/// by [`TestMemoryScope`].
#[cfg(any(test, feature = "testgen"))]
pub fn with_mock_scratch<R>(capacity: Option<u64>, f: impl FnOnce() -> R) -> R {
struct Reset(Option<Option<u64>>);
impl Drop for Reset {
fn drop(&mut self) {
MOCK_SCRATCH.with(|m| m.set(self.0));
}
}
let _reset = Reset(MOCK_SCRATCH.with(|m| m.replace(Some(capacity))));
f()
}
/// Explicit test-support capture/scope object to propagate the thread-local fixed mock snapshot
/// and the scoped PSD estimate charge across worker threads without modifying global process
/// state.
///
/// It captures `set_mock_memory`/`with_mock_memory`'s fixed snapshot and
/// [`crate::psd_budget::with_test_estimate_charge`]'s extra charge, so an engine worker that
/// enters the scope makes the same admission estimates as the test thread. The per-attempt
/// provider set by `with_mock_memory_provider` is not captured: that provider is a non-`Send`
/// closure re-consulted on every [`MemorySnapshot::current`], and propagating it to a worker
/// needs an explicitly shared, `Send + Sync` scope designed for that purpose (follow-up work).
/// A worker an import starts therefore sees the fixed snapshot, not a live provider.
///
/// Capturing is explicit: nothing here changes a thread that never enters the scope, and no
/// global state is written.
///
/// In production, this is an inert zero-overhead type.
#[derive(Clone, Copy, Debug, Default)]
pub struct TestMemoryScope {
#[cfg(any(test, feature = "testgen"))]
mock: Option<MemorySnapshot>,
/// The estimate charge captured with the scope (zero when the test set none).
#[cfg(any(test, feature = "testgen"))]
estimate_charge: u64,
/// The tile-pixel share of that charge.
#[cfg(any(test, feature = "testgen"))]
tile_charge: u64,
/// The mocked scratch disk ([`with_mock_scratch`]), if any.
#[cfg(any(test, feature = "testgen"))]
scratch: Option<Option<u64>>,
}
/// RAII guard that restores the previous thread-local mock memory and estimate charge upon drop.
pub struct TestMemoryGuard {
#[cfg(any(test, feature = "testgen"))]
prev: Option<MemorySnapshot>,
#[cfg(any(test, feature = "testgen"))]
prev_charge: (u64, u64),
#[cfg(any(test, feature = "testgen"))]
prev_scratch: Option<Option<u64>>,
}
#[cfg(any(test, feature = "testgen"))]
impl Drop for TestMemoryGuard {
fn drop(&mut self) {
MOCK_SNAPSHOT.with(|m| *m.borrow_mut() = self.prev);
crate::psd_budget::enter_test_estimate_charge(self.prev_charge.0, self.prev_charge.1);
MOCK_SCRATCH.with(|m| m.set(self.prev_scratch));
}
}
impl TestMemoryScope {
/// Captures the current thread's fixed mock memory snapshot and estimate charge, if any (see
/// [`TestMemoryScope`] for what is not captured).
///
/// Never captures actual system RAM as a permanent snapshot so that
/// production memory rechecks remain fresh.
pub fn capture() -> Self {
#[cfg(any(test, feature = "testgen"))]
{
let mock = MOCK_SNAPSHOT.with(|m| *m.borrow());
let (estimate_charge, tile_charge) = crate::psd_budget::test_estimate_charge();
Self { mock, estimate_charge, tile_charge, scratch: MOCK_SCRATCH.with(std::cell::Cell::get) }
}
#[cfg(not(any(test, feature = "testgen")))]
{
Self {}
}
}
/// Enters this captured mock memory scope, returning a RAII guard that
/// restores the thread's previous mock state and estimate charge on drop.
pub fn enter(self) -> TestMemoryGuard {
#[cfg(any(test, feature = "testgen"))]
{
let prev = MOCK_SNAPSHOT.with(|m| {
let old = *m.borrow();
*m.borrow_mut() = self.mock;
old
});
let prev_charge = crate::psd_budget::enter_test_estimate_charge(self.estimate_charge, self.tile_charge);
let prev_scratch = MOCK_SCRATCH.with(|m| m.replace(self.scratch));
TestMemoryGuard { prev, prev_charge, prev_scratch }
}
#[cfg(not(any(test, feature = "testgen")))]
{
TestMemoryGuard {}
}
}
/// Executes a closure within this captured mock memory scope.
pub fn run<R>(self, f: impl FnOnce() -> R) -> R {
let _guard = self.enter();
f()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn an_import_that_does_not_fit_is_refused() {
let gb = 1u64 << 30;
assert!(check_fits(10, 10, 4 * gb, None).is_ok(), "unknown: no check");
assert!(check_fits(10, 10, 4 * gb, Some(8 * gb)).is_ok());
assert!(check_fits(10, 10, 4 * gb, Some(4 * gb + RESERVE)).is_ok());
let e = check_fits(100_000, 100_000, 30 * gb, Some(16 * gb)).unwrap_err().to_string();
assert!(e.contains("not enough memory") && e.contains("100000 × 100000") && e.contains("32.2 GB"), "{e}");
assert!(check_fits(10, 10, 4 * gb, Some(4 * gb)).is_err(), "no room for the reserve");
assert!(check_fits(10, 10, u64::MAX, Some(u64::MAX)).is_err());
}
#[test]
fn pure_policy_adheres_to_approved_thresholds() {
if cfg!(target_arch = "wasm32") {
return; // the web policy has its own tests
}
if native_platform_cap() < 24 << 30 {
// This table uses 6-24 GiB limits, above a 32-bit aggregate cap.
return;
}
let gb = 1u64 << 30;
// 12 GiB RAM: H = min(9 GiB, 11 GiB) = 9 GiB; S = min(6 GiB, 8 GiB, 9 GiB) = 6 GiB.
let snap12 = MemorySnapshot { available_ram: Some(12 * gb), swap_free: None, commit_headroom: None };
let b12 = resolve_budget(snap12, None);
assert_eq!(b12.soft_limit, 6 * gb);
assert_eq!(b12.hard_limit, 9 * gb);
assert_eq!(b12.warning_threshold, None);
// 5.80 GiB estimate (5.8 * 1 GiB = 6227702579)
let est_5_8 = (5.80 * (gb as f64)).round() as u64;
assert_eq!(b12.decide(est_5_8), BudgetDecision::Automatic);
assert_eq!(b12.decide(6 * gb), BudgetDecision::Automatic);
assert_eq!(b12.decide(6 * gb + 1), BudgetDecision::RequiresApproval);
assert_eq!(b12.decide(9 * gb), BudgetDecision::RequiresApproval);
assert_eq!(b12.decide(9 * gb + 1), BudgetDecision::Refused);
// 8 GiB RAM: H = min(6 GiB, 7 GiB) = 6 GiB; S = min(4 GiB, 8 GiB, 6 GiB) = 4 GiB.
let snap8 = MemorySnapshot { available_ram: Some(8 * gb), swap_free: None, commit_headroom: None };
let b8 = resolve_budget(snap8, None);
assert_eq!(b8.soft_limit, 4 * gb);
assert_eq!(b8.hard_limit, 6 * gb);
assert_eq!(b8.decide(est_5_8), BudgetDecision::RequiresApproval);
// 6 GiB RAM: H = min(4.5 GiB, 5 GiB) = 4.5 GiB; S = 3 GiB.
let snap6 = MemorySnapshot { available_ram: Some(6 * gb), swap_free: None, commit_headroom: None };
let b6 = resolve_budget(snap6, None);
assert_eq!(b6.soft_limit, 3 * gb);
assert_eq!(b6.hard_limit, (4.5 * (gb as f64)) as u64);
assert_eq!(b6.decide(est_5_8), BudgetDecision::Refused);
// 32 GiB RAM: H = min(24 GiB, 31 GiB) = 24 GiB; S = min(16 GiB, 8 GiB, 24 GiB) = 8 GiB cap.
let snap32 = MemorySnapshot { available_ram: Some(32 * gb), swap_free: None, commit_headroom: None };
let b32 = resolve_budget(snap32, None);
assert_eq!(b32.soft_limit, 8 * gb);
assert_eq!(b32.hard_limit, 24 * gb);
assert_eq!(b32.warning_threshold, None);
assert!(!b32.requires_uncertainty_warning(10 * gb), "known memory has no unknown-capacity warning");
// Commit headroom constraint: C = 5 GiB -> C - 512 MiB = 4.5 GiB.
let snap_commit = MemorySnapshot { available_ram: Some(12 * gb), swap_free: None, commit_headroom: Some(5 * gb) };
let b_commit = resolve_budget(snap_commit, None);
assert_eq!(b_commit.hard_limit, 5 * gb - COMMIT_RESERVE);
assert_eq!(b_commit.soft_limit, 5 * gb - COMMIT_RESERVE);
// Caller limits: lowers admission, cannot raise past H.
let b_caller = resolve_budget(snap12, Some(5 * gb));
assert_eq!(b_caller.hard_limit, 5 * gb);
assert_eq!(b_caller.soft_limit, 5 * gb);
let b_caller_high = resolve_budget(snap8, Some(20 * gb));
assert_eq!(b_caller_high.hard_limit, 6 * gb);
assert_eq!(b_caller_high.soft_limit, 4 * gb);
}
#[test]
fn zero_available_ram_is_not_unknown() {
if cfg!(target_arch = "wasm32") {
return;
}
let snap_zero = MemorySnapshot { available_ram: Some(0), swap_free: None, commit_headroom: None };
let b_zero = resolve_budget(snap_zero, None);
assert_eq!(b_zero.soft_limit, 0);
assert_eq!(b_zero.hard_limit, 0);
assert_eq!(b_zero.warning_threshold, None);
assert_eq!(b_zero.decide(1), BudgetDecision::Refused);
let snap_unknown = MemorySnapshot::UNKNOWN;
let b_unknown = resolve_budget(snap_unknown, None);
assert_eq!(b_unknown.soft_limit, NATIVE_FALLBACK_BUDGET.min(native_platform_cap()));
assert_eq!(b_unknown.hard_limit, native_platform_cap());
assert_eq!(b_unknown.available_ram, None);
assert_eq!(b_unknown.warning_threshold, Some(UNKNOWN_MEMORY_WARNING_THRESHOLD));
assert_eq!(b_unknown.decide(1), BudgetDecision::Automatic);
let expected = if b_unknown.hard_limit > b_unknown.soft_limit { BudgetDecision::RequiresApproval } else { BudgetDecision::Automatic };
assert_eq!(b_unknown.decide(b_unknown.hard_limit.min(u64::MAX - 1)), expected);
assert_eq!(b_unknown.decide(u64::MAX), BudgetDecision::Refused, "the saturated overflow sentinel is never approved");
if b_unknown.hard_limit < u64::MAX {
assert_eq!(b_unknown.decide(b_unknown.hard_limit + 1), BudgetDecision::Refused);
}
}
/// A format estimate that overflows `u64` saturates at `u64::MAX`. Unknown native memory has
/// `u64::MAX` as its hard limit, so without a sentinel rule explicit approval would admit it.
#[test]
fn a_saturated_estimate_is_refused_even_at_the_unknown_native_hard_limit() {
if cfg!(target_pointer_width = "32") {
// A 32-bit aggregate cap already refuses it; the case this test guards is the
// 64-bit unknown-memory cap, where the limit itself is the sentinel.
return;
}
let budget = resolve_budget_for(Platform::Native, MemorySnapshot::UNKNOWN, None);
assert_eq!(budget.hard_limit, u64::MAX, "the case that would otherwise admit the sentinel");
assert_eq!(budget.decide(u64::MAX), BudgetDecision::Refused, "the decision agrees with evaluation");
assert_eq!(budget.decide(u64::MAX - 1), BudgetDecision::RequiresApproval);
for (approved, estimate) in [(false, None), (true, None), (true, Some(u64::MAX))] {
match evaluate_psd_admission_for(Platform::Native, u64::MAX, 0, 0, approved, estimate, MemorySnapshot::UNKNOWN) {
Err(IoError::PsdImportBudget { required, limit, .. }) => {
assert_eq!((required, limit), (u64::MAX, u64::MAX), "the typed refusal keeps the estimate and limit unchanged")
}
other => panic!("approved={approved}, estimate={estimate:?}: expected a hard refusal, got {other:?}"),
}
}
// A caller limit equal to the sentinel, or an approved estimate of it, is no exception.
assert!(matches!(
evaluate_psd_admission_for(Platform::Native, u64::MAX, 0, u64::MAX, true, Some(u64::MAX), MemorySnapshot::UNKNOWN),
Err(IoError::PsdImportBudget { required: u64::MAX, limit: u64::MAX, .. })
));
}
#[test]
fn unknown_memory_is_conservative_but_not_capped_at_eight_gib() {
if cfg!(target_pointer_width = "32") {
return;
}
let gb = 1u64 << 30;
let b = resolve_budget_for(Platform::Native, MemorySnapshot::UNKNOWN, None);
assert_eq!(b.soft_limit, NATIVE_FALLBACK_BUDGET);
assert_eq!(b.hard_limit, native_platform_cap());
assert_eq!(b.decide(NATIVE_FALLBACK_BUDGET), BudgetDecision::Automatic);
assert_eq!(b.decide(NATIVE_FALLBACK_BUDGET + 1), BudgetDecision::RequiresApproval);
assert_eq!(b.decide(UNKNOWN_MEMORY_WARNING_THRESHOLD), BudgetDecision::RequiresApproval);
assert!(!b.requires_uncertainty_warning(UNKNOWN_MEMORY_WARNING_THRESHOLD));
assert!(b.requires_uncertainty_warning(UNKNOWN_MEMORY_WARNING_THRESHOLD + 1));
assert_eq!(b.decide(UNKNOWN_MEMORY_WARNING_THRESHOLD + 1), BudgetDecision::RequiresApproval, "8 GiB is a warning threshold, not a hard ceiling");
assert_eq!(b.decide(64 * gb), BudgetDecision::RequiresApproval);
assert!(b.requires_uncertainty_warning(64 * gb));
}
#[test]
fn unknown_memory_with_known_commit_headroom_stays_conservative() {
if cfg!(target_arch = "wasm32") {
return;
}
let gb = 1u64 << 30;
let snap_zero = MemorySnapshot { available_ram: None, swap_free: None, commit_headroom: Some(0) };
let b_zero = resolve_budget(snap_zero, None);
assert_eq!(b_zero.hard_limit, 0);
assert_eq!(b_zero.soft_limit, 0);
assert_eq!(b_zero.decide(1), BudgetDecision::Refused);
let snap_tight = MemorySnapshot { available_ram: None, swap_free: None, commit_headroom: Some(gb) };
let b_tight = resolve_budget(snap_tight, None);
// 1 GiB of headroom keeps a quarter free (256 MiB), not the full 512 MiB.
assert_eq!(b_tight.hard_limit, 768 << 20);
assert_eq!(b_tight.soft_limit, 512 << 20);
let snap_room = MemorySnapshot { available_ram: None, swap_free: None, commit_headroom: Some(4 * gb) };
let b_room = resolve_budget(snap_room, None);
assert_eq!(b_room.hard_limit, 4 * gb - COMMIT_RESERVE);
assert_eq!(b_room.soft_limit, NATIVE_FALLBACK_BUDGET);
}
#[test]
fn unknown_memory_admits_approved_imports_above_eight_gib() {
if cfg!(target_pointer_width = "32") {
return; // the 32-bit platform cap is below 8 GiB
}
let gb = 1u64 << 30;
let snap = MemorySnapshot::UNKNOWN;
let required = 9 * gb;
let err = evaluate_psd_admission_for(Platform::Native, required, 0, 0, false, None, snap).unwrap_err();
assert!(matches!(err, IoError::PsdApprovalRequired { available_ram: None, .. }));
let out = evaluate_psd_admission_for(Platform::Native, required, 0, 0, true, Some(required), snap).unwrap();
assert_eq!(out.authorized_total, required);
assert!(out.budget.requires_uncertainty_warning(required), "the consent warning must carry through admission");
let err = evaluate_psd_admission_for(Platform::Native, required, 0, 0, true, Some(required - 1), snap).unwrap_err();
assert!(matches!(err, IoError::PsdApprovalRequired { .. }), "a larger estimate needs fresh consent");
}
#[test]
fn web_policy_allows_approval_above_one_gib_within_its_own_cap() {
let b = resolve_budget_for(Platform::Web, MemorySnapshot::UNKNOWN, None);
assert_eq!(b.soft_limit, WASM_BUDGET);
assert_eq!(b.hard_limit, WASM_MAX_PEAK_BUDGET);
assert!(b.hard_limit < WASM_LINEAR_MEMORY_LIMIT, "the aggregate cap stays below the wasm32 address space");
const { assert!(WASM_MAX_SINGLE_ALLOCATION < WASM_LINEAR_MEMORY_LIMIT, "a single Rust allocation cannot use all 4 GiB") };
assert_eq!(b.available_ram, None);
assert_eq!(b.warning_threshold, None);
assert_eq!(b.decide(WASM_BUDGET), BudgetDecision::Automatic);
assert_eq!(b.decide(WASM_BUDGET + 1), BudgetDecision::RequiresApproval);
assert_eq!(b.decide(WASM_MAX_PEAK_BUDGET), BudgetDecision::RequiresApproval);
assert_eq!(b.decide(WASM_MAX_PEAK_BUDGET + 1), BudgetDecision::Refused);
const { assert!(WASM_MAX_SINGLE_ALLOCATION < WASM_MAX_PEAK_BUDGET, "the aggregate cap must not be the single-allocation layout bound") };
let out = evaluate_psd_admission_for(Platform::Web, WASM_MAX_PEAK_BUDGET, 0, 0, true, Some(WASM_MAX_PEAK_BUDGET), MemorySnapshot::UNKNOWN).unwrap();
assert_eq!(out.authorized_total, WASM_MAX_PEAK_BUDGET, "approval may authorize an aggregate above one buffer's layout limit");
let capped = resolve_budget_for(Platform::Web, MemorySnapshot::UNKNOWN, Some(512 << 20));
assert_eq!(capped.hard_limit, 512 << 20);
assert_eq!(capped.soft_limit, 512 << 20);
let no_raise = resolve_budget_for(Platform::Web, MemorySnapshot::UNKNOWN, Some(64 << 30));
assert_eq!(no_raise.hard_limit, WASM_MAX_PEAK_BUDGET);
}
#[test]
fn web_admission_requires_approval_above_its_automatic_allowance() {
let snap = MemorySnapshot::UNKNOWN;
let approval = 3 * (WASM_BUDGET / 2);
let out = evaluate_psd_admission_for(Platform::Web, WASM_BUDGET, 0, 0, false, None, snap).unwrap();
assert_eq!(out.authorized_total, WASM_BUDGET);
let err = evaluate_psd_admission_for(Platform::Web, WASM_BUDGET + 1, 0, 0, false, None, snap).unwrap_err();
assert!(matches!(
err,
IoError::PsdApprovalRequired { required, soft_limit, hard_limit, available_ram }
if required == WASM_BUDGET + 1 && soft_limit == WASM_BUDGET && hard_limit == WASM_MAX_PEAK_BUDGET && available_ram.is_none()
));
let out = evaluate_psd_admission_for(Platform::Web, approval, 0, 0, true, Some(approval), snap).unwrap();
assert_eq!(out.authorized_total, approval);
let err = evaluate_psd_admission_for(Platform::Web, approval, 0, 0, true, Some(approval - 1), snap).unwrap_err();
assert!(matches!(err, IoError::PsdApprovalRequired { .. }));
let err = evaluate_psd_admission_for(Platform::Web, WASM_MAX_PEAK_BUDGET + 1, 0, 0, true, None, snap).unwrap_err();
assert!(matches!(err, IoError::PsdImportBudget { .. }));
}
#[test]
fn caller_caps_lower_unknown_memory_admission() {
let b = resolve_budget_for(Platform::Native, MemorySnapshot::UNKNOWN, Some(1 << 30));
assert_eq!(b.hard_limit, 1 << 30);
assert_eq!(b.soft_limit, 1 << 30);
assert_eq!(b.warning_threshold, Some(UNKNOWN_MEMORY_WARNING_THRESHOLD));
let no_raise = resolve_budget_for(Platform::Native, MemorySnapshot::UNKNOWN, Some(64 << 30));
assert_eq!(no_raise.hard_limit, native_platform_cap().min(64 << 30));
assert_eq!(no_raise.soft_limit, NATIVE_FALLBACK_BUDGET.min(native_platform_cap()));
}
#[test]
fn arithmetic_overflow_safety() {
if cfg!(target_arch = "wasm32") {
return;
}
let snap_huge = MemorySnapshot { available_ram: Some(u64::MAX), swap_free: Some(u64::MAX), commit_headroom: Some(u64::MAX) };
let b = resolve_budget(snap_huge, None);
let expected_hard = (((u64::MAX as u128) * 3) / 4) as u64;
let expected_hard = expected_hard.min(native_platform_cap());
assert_eq!(b.hard_limit, expected_hard);
assert_eq!(b.soft_limit, MAX_SOFT_BUDGET.min(expected_hard));
}
#[test]
fn nested_mock_memory_restores_previous() {
let snap1 = MemorySnapshot { available_ram: Some(100), swap_free: None, commit_headroom: None };
let snap2 = MemorySnapshot { available_ram: Some(200), swap_free: None, commit_headroom: None };
with_mock_memory(MemorySnapshot::UNKNOWN, || {
assert_eq!(MemorySnapshot::current(), MemorySnapshot::UNKNOWN);
with_mock_memory(snap1, || {
assert_eq!(MemorySnapshot::current().available_ram, Some(100));
with_mock_memory(snap2, || {
assert_eq!(MemorySnapshot::current().available_ram, Some(200));
});
assert_eq!(MemorySnapshot::current().available_ram, Some(100));
});
assert_eq!(MemorySnapshot::current(), MemorySnapshot::UNKNOWN);
});
}
#[test]
fn central_admission_evaluation_enforces_bounds() {
if cfg!(any(target_arch = "wasm32", target_pointer_width = "32")) {
return;
}
let gb = 1u64 << 30;
let snap = MemorySnapshot { available_ram: Some(12 * gb), swap_free: None, commit_headroom: None };
// S = 6 GiB, H = 9 GiB
// Below S: automatic, authorized_total = S (6 GiB)
let out = evaluate_psd_admission(5 * gb, 0, 0, false, None, snap).unwrap();
assert_eq!(out.authorized_total, 6 * gb);
// In [S, H]: requires approval
let err = evaluate_psd_admission(7 * gb, 0, 0, false, None, snap).unwrap_err();
assert!(matches!(err, IoError::PsdApprovalRequired { required, .. } if required == 7 * gb));
// In [S, H] with approval and no approved_estimate bound: admitted, authorized_total = H (9 GiB)
let out = evaluate_psd_admission(7 * gb, 0, 0, true, None, snap).unwrap();
assert_eq!(out.authorized_total, 9 * gb);
// In [S, H] with approval but required exceeds approved_estimate: requires fresh approval
let err = evaluate_psd_admission(7 * gb, 0, 0, true, Some(6 * gb), snap).unwrap_err();
assert!(matches!(err, IoError::PsdApprovalRequired { .. }));
// In [S, H] with approval and required within approved_estimate: admitted, authorized_total = approved_estimate (7 GiB)
let out = evaluate_psd_admission(7 * gb, 0, 0, true, Some(7 * gb), snap).unwrap();
assert_eq!(out.authorized_total, 7 * gb);
// Exceeding H: refused even if high_memory_approved is true
let err = evaluate_psd_admission(10 * gb, 0, 0, true, Some(10 * gb), snap).unwrap_err();
assert!(matches!(err, IoError::PsdImportBudget { .. }));
}
/// While the scratch disk spills, tile pixels are admitted against RAM plus its room, and
/// everything else against RAM alone.
#[test]
fn spilling_scratch_admits_tile_pixels_beyond_ram() {
if cfg!(any(target_arch = "wasm32", target_pointer_width = "32")) {
return;
}
let gb = 1u64 << 30;
let snap = MemorySnapshot { available_ram: Some(12 * gb), swap_free: None, commit_headroom: None };
// RAM-only: S = 6 GiB, H = 9 GiB.
with_mock_scratch(Some(40 * gb), || {
// 20 GiB of which 18 GiB tiles: 2 GiB non-spillable fits S, so it is automatic.
let out = evaluate_psd_admission(20 * gb, 18 * gb, 0, false, None, snap).unwrap();
assert_eq!(out.authorized_total, 6 * gb + 18 * gb);
// 8 GiB non-spillable sits in [S, H]: approval is still required, and is bound to
// the whole estimate.
let err = evaluate_psd_admission(26 * gb, 18 * gb, 0, false, None, snap).unwrap_err();
assert!(matches!(err, IoError::PsdApprovalRequired { required, soft_limit, hard_limit, .. }
if required == 26 * gb && soft_limit == 24 * gb && hard_limit == 27 * gb));
assert!(evaluate_psd_admission(26 * gb, 18 * gb, 0, true, Some(26 * gb), snap).is_ok());
assert!(evaluate_psd_admission(26 * gb, 18 * gb, 0, true, Some(26 * gb - 1), snap).is_err());
// 10 GiB non-spillable is over H: refused even when approved.
let err = evaluate_psd_admission(28 * gb, 18 * gb, 0, true, Some(28 * gb), snap).unwrap_err();
assert!(matches!(err, IoError::PsdImportBudget { required, limit, .. } if required == 28 * gb && limit == 27 * gb));
// A spillable share claimed beyond the total is clamped to the total.
assert!(evaluate_psd_admission(5 * gb, u64::MAX, 0, false, None, snap).is_ok());
// The caller's explicit limit still bounds the whole import.
let err = evaluate_psd_admission(20 * gb, 18 * gb, 10 * gb, false, None, snap).unwrap_err();
assert!(matches!(err, IoError::PsdImportBudget { limit, .. } if limit == 10 * gb));
});
// Less room than tiles: only the room is credited.
with_mock_scratch(Some(4 * gb), || {
let err = evaluate_psd_admission(20 * gb, 18 * gb, 0, true, Some(20 * gb), snap).unwrap_err();
assert!(matches!(err, IoError::PsdImportBudget { limit, .. } if limit == 13 * gb));
assert_eq!(resolve_budget_with_scratch(snap, None, 18 * gb).soft_limit, 10 * gb);
});
}
/// Spilling off or paused, or the web: the RAM-only policy, unchanged.
#[test]
fn without_spilling_scratch_the_ram_policy_is_unchanged() {
if cfg!(any(target_arch = "wasm32", target_pointer_width = "32")) {
return;
}
let gb = 1u64 << 30;
let snap = MemorySnapshot { available_ram: Some(12 * gb), swap_free: None, commit_headroom: None };
for scratch in [None, Some(0)] {
with_mock_scratch(scratch, || {
assert_eq!(resolve_budget_with_scratch(snap, None, 18 * gb), resolve_budget(snap, None));
let err = evaluate_psd_admission(20 * gb, 18 * gb, 0, true, Some(20 * gb), snap).unwrap_err();
assert!(matches!(err, IoError::PsdImportBudget { limit, .. } if limit == 9 * gb));
let err = evaluate_psd_admission(7 * gb, 7 * gb, 0, false, None, snap).unwrap_err();
assert!(matches!(err, IoError::PsdApprovalRequired { soft_limit, hard_limit, .. } if soft_limit == 6 * gb && hard_limit == 9 * gb));
});
}
// A mocked RAM snapshot without a mocked scratch disk never measures the real one.
with_mock_memory(snap, || assert_eq!(scratch_capacity(), None));
with_mock_scratch(Some(40 * gb), || {
assert_eq!(scratch_credit_for(Platform::Web, 18 * gb), 0);
let err = evaluate_psd_admission_for(Platform::Web, WASM_BUDGET + 1, WASM_BUDGET, 0, false, None, snap).unwrap_err();
assert!(matches!(err, IoError::PsdApprovalRequired { soft_limit, .. } if soft_limit == WASM_BUDGET));
let err = evaluate_psd_admission_for(Platform::Web, WASM_MAX_PEAK_BUDGET + 1, WASM_MAX_PEAK_BUDGET, 0, true, None, snap).unwrap_err();
assert!(matches!(err, IoError::PsdImportBudget { .. }));
});
}
/// A [`TestMemoryScope`] carries the mocked scratch disk to a worker thread.
#[test]
fn test_memory_scope_captures_the_mocked_scratch_disk() {
let scope = with_mock_scratch(Some(123), TestMemoryScope::capture);
std::thread::spawn(move || {
assert_eq!(MOCK_SCRATCH.with(std::cell::Cell::get), None);
let _g = scope.enter();
assert_eq!(scratch_capacity(), Some(123));
})
.join()
.unwrap();
}
#[test]
fn known_snapshot_uses_known_memory_policy_on_every_target() {
let gb = 1u64 << 30;
let snap = MemorySnapshot { available_ram: Some(16 * gb), swap_free: None, commit_headroom: None };
let b = resolve_budget_for(Platform::Native, snap, None);
let expected_hard = (12 * gb).min(native_platform_cap());
assert_eq!(b.hard_limit, expected_hard);
assert_eq!(b.soft_limit, (8 * gb).min(expected_hard));
assert_eq!(b.available_ram, Some(16 * gb));
assert_eq!(b.warning_threshold, None);
}
#[test]
fn aggregate_cap_is_not_a_single_allocation_bound() {
let cap = native_platform_cap();
if cfg!(target_pointer_width = "32") {
assert_eq!(cap, NATIVE_32BIT_PEAK_CAP, "32-bit native uses the documented product cap");
} else {
assert_eq!(cap, u64::MAX, "64-bit native has no measurable aggregate address-space cap");
assert!(MAX_SINGLE_ALLOCATION < cap, "a per-buffer limit must not become the aggregate limit");
}
}
#[test]
fn swap_is_never_part_of_the_adaptive_budget() {
let gb = 1u64 << 30;
let with_swap = MemorySnapshot { available_ram: Some(4 * gb), swap_free: Some(64 * gb), commit_headroom: None };
let without_swap = MemorySnapshot { available_ram: Some(4 * gb), swap_free: None, commit_headroom: None };
assert_eq!(resolve_budget_for(Platform::Native, with_swap, None), resolve_budget_for(Platform::Native, without_swap, None));
}
const MIB: u64 = 1 << 20;
const GIB: u64 = 1 << 30;
fn native_budget(ram: Option<u64>, commit: Option<u64>) -> MemoryBudget {
resolve_budget_for(Platform::Native, MemorySnapshot { available_ram: ram, swap_free: None, commit_headroom: commit }, None)
}
fn hard_refusal(result: Result<AdmissionOutcome, IoError>) -> (u64, u64, Option<u64>) {
match result {
Err(IoError::PsdImportBudget { required, limit, free_memory }) => (required, limit, free_memory),
other => panic!("expected a hard refusal, got {other:?}"),
}
}
#[test]
fn low_ram_boundaries_keep_room_for_small_files() {
if cfg!(any(target_arch = "wasm32", target_pointer_width = "32")) {
return;
}
// (free RAM, soft limit, hard limit)
let table = [
(0, 0, 0),
(128 * MIB, 0, 0),
(256 * MIB, 0, 0),
(256 * MIB + 1, 64 * MIB, 1),
(512 * MIB, 128 * MIB, 256 * MIB),
(GIB, 256 * MIB, 768 * MIB),
(GIB + 1, 256 * MIB, 768 * MIB),
(1366 * MIB, 342 * MIB, 2049 * MIB / 2),
(3 * GIB / 2, 512 * MIB, 1152 * MIB),
(2 * GIB, GIB, 3 * GIB / 2),
(3 * GIB, 3 * GIB / 2, 9 * GIB / 4),
(4 * GIB, 2 * GIB, 3 * GIB),
(8 * GIB, 4 * GIB, 6 * GIB),
];
for (ram, soft, hard) in table {
let b = native_budget(Some(ram), None);
// The soft limit is also bounded by the hard limit: 256 MiB + 1 leaves 1 byte.
let soft = soft.min(hard);
assert_eq!((b.soft_limit, b.hard_limit), (soft, hard), "free RAM {ram}");
assert_eq!(b.warning_threshold, None);
}
}
#[test]
fn low_commit_boundaries_keep_room_for_small_files() {
if cfg!(any(target_arch = "wasm32", target_pointer_width = "32")) {
return;
}
// (commit headroom, soft limit, hard limit) with plenty of RAM, then with RAM unknown.
let table = [
(0, 0, 0),
(128 * MIB, 0, 0),
(256 * MIB, 0, 0),
(512 * MIB, 128 * MIB, 256 * MIB),
(512 * MIB + 1, 128 * MIB, 256 * MIB + 1),
(GIB, 512 * MIB, 768 * MIB),
(3 * GIB / 2, GIB, 1152 * MIB),
(2 * GIB, 3 * GIB / 2, 3 * GIB / 2),
(5 * GIB, 9 * GIB / 2, 9 * GIB / 2),
];
for (commit, soft, hard) in table {
let b = native_budget(Some(64 * GIB), Some(commit));
assert_eq!((b.soft_limit, b.hard_limit), (soft, hard), "commit {commit}, RAM known");
let unknown = native_budget(None, Some(commit));
assert_eq!(unknown.hard_limit, hard, "commit {commit}, RAM unknown");
assert_eq!(unknown.soft_limit, soft.min(2 * GIB), "commit {commit}, RAM unknown");
assert_eq!(unknown.warning_threshold, Some(UNKNOWN_MEMORY_WARNING_THRESHOLD));
}
}
#[test]
fn budgets_grow_with_free_memory_and_leave_the_reserve() {
if cfg!(any(target_arch = "wasm32", target_pointer_width = "32")) {
return;
}
for by_commit in [false, true] {
let (mut last_soft, mut last_hard) = (0, 0);
let mut measured = 0;
while measured <= 9 * GIB {
let b = if by_commit { native_budget(Some(64 * GIB), Some(measured)) } else { native_budget(Some(measured), None) };
assert!(b.soft_limit <= b.hard_limit, "commit={by_commit} {measured}");
assert!(b.hard_limit <= measured, "commit={by_commit} {measured}");
assert!(b.soft_limit >= last_soft && b.hard_limit >= last_hard, "commit={by_commit} {measured}: not non-decreasing");
if b.hard_limit > 0 {
assert!(measured - b.hard_limit >= LOW_MEMORY_RESERVE, "commit={by_commit} {measured}: reserve not kept");
}
(last_soft, last_hard) = (b.soft_limit, b.hard_limit);
measured += 16 * MIB;
}
}
}
#[test]
fn a_small_file_opens_on_a_machine_with_little_free_memory() {
if cfg!(any(target_arch = "wasm32", target_pointer_width = "32")) {
return;
}
let b = native_budget(Some(900 * MIB), None);
assert_eq!(b.decide(100 * MIB), BudgetDecision::Automatic);
assert_eq!(b.decide(300 * MIB), BudgetDecision::RequiresApproval);
assert_eq!(b.decide(700 * MIB), BudgetDecision::Refused);
// The reported case: about 190 MB beyond 1 GiB free.
let snap = MemorySnapshot { available_ram: Some(190_693_376 + GIB), swap_free: None, commit_headroom: None };
let (required, limit, free) = hard_refusal(evaluate_psd_admission_for(Platform::Native, 1_136_504_592, 0, 0, false, None, snap));
assert_eq!((required, limit), (1_136_504_592, (190_693_376 + GIB) * 3 / 4));
assert_eq!(free, Some(190_693_376 + GIB));
assert!(matches!(evaluate_psd_admission_for(Platform::Native, 500_000_000, 0, 0, false, None, snap), Err(IoError::PsdApprovalRequired { .. })));
}
#[test]
fn refusals_report_free_memory_only_when_measured_memory_set_the_limit() {
if cfg!(any(target_arch = "wasm32", target_pointer_width = "32")) {
return;
}
let snap = |ram, commit| MemorySnapshot { available_ram: ram, swap_free: None, commit_headroom: commit };
let refuse = |required, caller, snapshot| hard_refusal(evaluate_psd_admission_for(Platform::Native, required, 0, caller, false, None, snapshot));
// RAM binds.
assert_eq!(refuse(2 * GIB, 0, snap(Some(GIB), None)), (2 * GIB, 768 * MIB, Some(GIB)));
// Commit headroom below RAM binds.
assert_eq!(refuse(2 * GIB, 0, snap(Some(64 * GIB), Some(GIB))), (2 * GIB, 768 * MIB, Some(GIB)));
// Commit headroom alone (RAM unknown).
assert_eq!(refuse(2 * GIB, 0, snap(None, Some(GIB))), (2 * GIB, 768 * MIB, Some(GIB)));
// Zero measured RAM (also the fail-closed unreadable limit) refuses everything.
assert_eq!(refuse(1, 0, snap(Some(0), None)), (1, 0, Some(0)));
// A binding caller limit is not the machine's.
assert_eq!(refuse(2 * GIB, GIB, snap(Some(8 * GIB), None)), (2 * GIB, GIB, None));
assert_eq!(refuse(2 * GIB, GIB, MemorySnapshot::UNKNOWN), (2 * GIB, GIB, None));
// The overflow sentinel is not helped by closing apps.
assert_eq!(refuse(u64::MAX, 0, snap(Some(8 * GIB), None)), (u64::MAX, 6 * GIB, None));
assert_eq!(refuse(u64::MAX, 0, MemorySnapshot::UNKNOWN), (u64::MAX, u64::MAX, None));
// On the budget itself.
assert_eq!(native_budget(Some(8 * GIB), None).measured_free, Some(8 * GIB));
assert_eq!(native_budget(Some(8 * GIB), None).refusal_free_memory(u64::MAX), None);
assert_eq!(native_budget(None, None).measured_free, None);
assert_eq!(resolve_budget_for(Platform::Web, snap(Some(GIB), None), None).measured_free, None);
// A caller limit equal to the machine's limit does not hide the measurement.
assert_eq!(resolve_budget_for(Platform::Native, snap(Some(8 * GIB), None), Some(6 * GIB)).measured_free, Some(8 * GIB));
assert_eq!(resolve_budget_for(Platform::Native, snap(Some(8 * GIB), None), Some(6 * GIB - 1)).measured_free, None);
}
/// Only 32-bit native has a finite cap: when it equals the measured room, freeing memory
/// cannot raise the limit, so no free-memory figure is reported.
#[test]
fn a_platform_cap_equal_to_the_measured_room_reports_no_free_memory() {
let cap = native_platform_cap();
if cap == u64::MAX {
return;
}
assert_eq!(native_budget(None, Some(cap + COMMIT_RESERVE)).measured_free, None);
assert_eq!(native_budget(None, Some(cap - 1 + COMMIT_RESERVE)).measured_free, Some(cap - 1 + COMMIT_RESERVE));
}
#[test]
fn scratch_credit_adds_to_the_low_memory_limits() {
if cfg!(any(target_arch = "wasm32", target_pointer_width = "32")) {
return;
}
let snap = |ram, commit| MemorySnapshot { available_ram: ram, swap_free: None, commit_headroom: commit };
with_mock_scratch(Some(40 * GIB), || {
let one_gib = snap(Some(GIB), None);
let out = evaluate_psd_admission_for(Platform::Native, 2 * GIB + 100 * MIB, 2 * GIB, 0, false, None, one_gib).unwrap();
assert_eq!(out.authorized_total, 256 * MIB + 2 * GIB);
let err = evaluate_psd_admission_for(Platform::Native, 2 * GIB + 500 * MIB, 2 * GIB, 0, false, None, one_gib).unwrap_err();
assert!(matches!(err, IoError::PsdApprovalRequired { soft_limit, hard_limit, .. }
if soft_limit == 2 * GIB + 256 * MIB && hard_limit == 2 * GIB + 768 * MIB));
let refused = hard_refusal(evaluate_psd_admission_for(Platform::Native, 2 * GIB + 800 * MIB, 2 * GIB, 0, true, None, one_gib));
assert_eq!(refused, (2 * GIB + 800 * MIB, 2 * GIB + 768 * MIB, Some(GIB)));
// Fail closed: nothing measured, so only the credited tile share passes.
let zero = snap(Some(0), None);
assert!(evaluate_psd_admission_for(Platform::Native, 2 * GIB, 2 * GIB, 0, false, None, zero).is_ok());
let refused = hard_refusal(evaluate_psd_admission_for(Platform::Native, 2 * GIB + 1, 2 * GIB, 0, true, None, zero));
assert_eq!(refused, (2 * GIB + 1, 2 * GIB, Some(0)));
// Low commit headroom with plenty of RAM: H = 256 MiB + credit.
let low_commit = snap(Some(64 * GIB), Some(512 * MIB));
let refused = hard_refusal(evaluate_psd_admission_for(Platform::Native, 2 * GIB + 300 * MIB, 2 * GIB, 0, true, None, low_commit));
assert_eq!(refused, (2 * GIB + 300 * MIB, 2 * GIB + 256 * MIB, Some(512 * MIB)));
let b = resolve_budget_credited(Platform::Native, low_commit, None, 2 * GIB);
assert_eq!((b.soft_limit, b.hard_limit), (2 * GIB + 128 * MIB, 2 * GIB + 256 * MIB));
});
}
#[test]
fn low_memory_advice_names_the_free_memory() {
assert_eq!(low_memory_advice(&None), "");
assert_eq!(
low_memory_advice(&Some(0)),
". PhotoCraft measured no free memory, or could not read this system's memory limit. Close other apps and try again"
);
assert_eq!(low_memory_advice(&Some(900 << 20)), ". About 900 MiB of memory is free. Close other apps and try again");
assert_eq!(low_memory_advice(&Some(3 << 30)), ". About 3.0 GiB of memory is free. Close other apps and try again");
assert_eq!(low_memory_advice(&Some(512)), ". About 512 B of memory is free. Close other apps and try again");
}
}