Struct MemoryBudget 

pub struct MemoryBudget { /* private fields */ }

Process-wide coordinator that periodically reapportions cache capacities so the application stays close to its target RSS.

Construct via MemoryBudget::new or MemoryBudget::from_env. Register every cache via MemoryBudget::register. Start the background tick via MemoryBudget::spawn.

Implementations

impl MemoryBudget

pub fn observed_usage_bytes(&self) -> u64

Observe current process/allocator usage without running a cache tick.

This is a measurement, not an allocation reservation. The maximum of process usage, allocator residency and live heap bytes protects against both compressed pages and allocations outside the configured allocator.

pub fn lease(&self, bytes: u64) -> LeaseGuard

Reserve bytes, panicking if outstanding leases would exceed the target.

Use Self::try_lease when exhaustion is an expected refusal. The reservation must precede allocation and follow its ownership to release. This bounds outstanding reservations, not unregistered allocations.

Panics

Panics when the aggregate reservation would exceed the target.

pub fn try_lease(&self, bytes: u64) -> Result<LeaseGuard, ReservationError>

Reserve bytes atomically without exceeding the aggregate lease target.

Registered cache ceilings are reduced by active leases on the next coordination tick. Existing allocations are not synchronously evicted; callers must account for cache/baseline ownership separately before claiming an enforced whole-process allocation bound.

Errors

Returns ReservationError without changing accounting when the request cannot fit. No payload is allocated and no waiter is queued.

pub fn target_bytes(&self) -> u64

Soft RSS target in bytes, before any lease deductions.

pub fn effective_target_bytes(&self) -> u64

Effective target after subtracting admitted active leases.

pub fn executor_spill_run_buffer_bytes(&self) -> usize

Per-operator external-sort run buffer for executor spill paths.

Derived from the effective process target, so active leases shrink executor spill buffers before an operator starts rather than letting every operator size itself against the whole process budget.

Panics

Panics if the bounded spill-buffer size cannot fit in usize.

pub fn result_channel_bytes(&self) -> usize

Byte budget for one result stream’s producer→consumer channel (BME-22): the ceiling on encoded result bytes in flight between the encoder and its consumer/spool tee. A byte bound, not a frame count — frames vary in size by orders of magnitude, so counting them would bound the wrong quantity (BME-12’s lesson).

Derived from the effective process target so active leases shrink in-flight result buffering the same way they shrink spill buffers.

Panics

Panics if the bounded channel size cannot fit in usize.

pub fn tick_interval(&self) -> Duration

Tick cadence used by the spawned background loop.

pub fn hard_ceiling_bytes(&self) -> Option<u64>

Optional hard ceiling. When set, the budget aborts the process if RSS exceeds this value — a backstop for runaway growth in production.

impl MemoryBudget

pub fn new(config: BudgetConfig) -> Self

Construct a budget from an explicit config and the default RSS source and policy. Caller is responsible for spawning the background ticker via MemoryBudget::spawn.

pub fn from_env() -> Self

Convenience constructor that resolves config from environment using the system RAM reported by the default SystemRss.

pub fn start() -> Arc<Self>

Non-jemalloc fallback for builds that don’t link tikv-jemallocator (e.g. Windows-msvc, where the tikv-jemalloc-sys build needs an MSYS2/autoconf toolchain we don’t provide). Builds a budget with the default RSS source, spawns the ticker, and emits the same initialised breadcrumb so application startup logs stay consistent across platforms. The jemalloc-stats columns will read zero.

pub fn with_rss(config: BudgetConfig, rss: Box<dyn RssSource>) -> Self

Construct with a custom RssSource (used by tests).

pub fn with_jemalloc_stats(self, source: Box<dyn JemallocStatsSource>) -> Self

Install a JemallocStatsSource so the budget tick can split the non-cache bucket into “live allocations” vs “retained-by-jemalloc pages”. Must be called before any cache is registered.

Panics

Panics if any cache is already registered, or if the budget’s internal state has been cloned (e.g. the ticker is already spawned).

pub fn with_policy(self, policy: Box<dyn Policy>) -> Self

Replace the default policy. Mostly used in tests; production stays on ProportionalPolicy until benchmark data argues otherwise.

Panics

Panics if any cache is already registered — the new policy must be installed before registration so that caches see a consistent reapportionment regime.

pub fn register(&self, cache: &Arc<dyn Resizable>)

Register a cache. The cache’s current max_bytes is captured as its preferred ceiling — the policy will never grow a cache above this value.

Panics

Panics if the internal registrations lock is poisoned.

pub fn register_reporter(&self, reporter: &Arc<dyn NonCacheReporter>)

Register a read-only NonCacheReporter so the tick can attribute a named slice of the non_cache_live bucket to it. The budget holds a Weak, so dropping the reporter prunes it from the next tick. Unlike caches, reporters are never resized.

Panics

Panics if the internal reporters lock is poisoned.

impl MemoryBudget

pub fn tick_now(&self) -> BudgetSnapshot

Run one reapportionment tick synchronously. Returns the snapshot used for diagnostic emission. Exposed publicly so tests can drive the budget without spawning a tokio task.

pub fn spawn(&self) -> JoinHandle<()>

Spawn a background tokio task that calls MemoryBudget::tick_now at the configured cadence. Returns a handle that aborts the task on drop.