856f865cf98d
memory.rs
//! 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
/// (`craft-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");
}
}
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.