spacr.qt.memory_budget

Cache eviction policies and host-memory availability measurements.

The idle timeout and cache ceiling determine the keys selected by what_to_drop. The separate headroom_is_short predicate compares available host memory with a configured threshold. Callers apply these policies and perform resource cleanup.

This module does not unload Python modules or native libraries. Eviction plans identify cache entries; callers decide which resources may be released. The policies do not guarantee a particular reduction in process memory or GPU allocations.

Functions

free_megabytes(→ Optional[float])	Return available host memory in mebibytes.
headroom_is_short(→ bool)	Test whether available host memory is below the configured threshold.
recommended_for(level)	The suggested budget for a performance level.
what_to_drop(→ list)	Select cache keys by idle timeout and then the remaining total size.

Module Contents

spacr.qt.memory_budget.free_megabytes() → float | None

Return available host memory in mebibytes.

Returns:

psutil.virtual_memory().available divided by 1024**2, or None when the measurement fails.

spacr.qt.memory_budget.headroom_is_short(floor_mb: float | None = None) → bool

Test whether available host memory is below the configured threshold.

Parameters:

floor_mb – threshold in mebibytes; read from preferences when omitted.

Returns:

False when memory or the required preference cannot be read; otherwise the result of comparing available memory with the threshold.

spacr.qt.memory_budget.recommended_for(level: str)

The suggested budget for a performance level.

Parameters:

level – one of spacr.qt.preferences.PERFORMANCE_LEVELS.

Returns:

(idle_minutes, cache_mb, headroom_mb).

spacr.qt.memory_budget.what_to_drop(entries, now: float, idle_minutes: float | None = None, ceiling_mb: int | None = None) → list

Select cache keys by idle timeout and then the remaining total size.

Parameters:

• entries – [(key, megabytes, last_used_epoch_seconds), ...].

• now – the current epoch time, passed in so a test can choose it.

• idle_minutes – the idle timeout; from preferences when omitted.

• ceiling_mb – the size ceiling; from preferences when omitted.

Returns:

string keys to drop, in selection order.

Entries older than the timeout are selected first, in input order. If the remaining total exceeds the ceiling, additional entries are selected from least to most recently used until that total fits.

Size determines whether further eviction is needed, not the ranking. The ceiling can select entries even when none exceeds the idle timeout. This helper does not check host-memory headroom or whether entries are in use; callers must supply entries eligible for eviction.