Struct MemoryGovernor 

pub struct MemoryGovernor { /* private fields */ }

The node-level memory governor (S1E-003). Cheap to clone (one Arc); thread-safe; the reservation fast path is lock-free and allocation-free.

Implementations

impl MemoryGovernor

pub fn new(config: GovernorConfig) -> Result<Self, MemoryError>

A governor over config (validated).

pub fn with_max_bytes(max_bytes: u64) -> Result<Self, MemoryError>

A governor with the default configuration for max_bytes.

pub fn config(&self) -> &GovernorConfig

The governor’s configuration.

pub fn max_bytes(&self) -> u64

Configured node maximum in bytes.

pub fn reserved_floor_bytes(&self) -> u64

Configured reserved floor in bytes.

pub fn class_budget(&self, class: MemoryClass) -> u64

Configured budget of one class.

pub fn usage(&self, class: MemoryClass) -> u64

Currently reserved bytes of one class.

pub fn total_used(&self) -> u64

Currently reserved bytes across all classes.

pub fn pressure(&self) -> f64

Fraction of the configured maximum in use, clamped to 0.0..=1.0.

pub fn escalation(&self) -> EscalationLevel

The current escalation level (with hysteresis applied).

pub fn should_reject_low_priority_work(&self) -> bool

Step 1 active: new low-priority work is being rejected.

pub fn should_evict_caches(&self) -> bool

Step 2 active: reclaimable caches should be evicted (evict_reclaimable drives them).

pub fn spill_trigger(&self) -> bool

Step 3 active: eligible query operators should spill. Exposed to the S1E-004 spill path: request_spill_grant turns the signal into a typed grant; the disk side is crate::spill::SpillManager.

pub fn should_throttle_maintenance(&self) -> bool

Step 4 active: maintenance work should be throttled (§13.1).

pub fn try_reserve( &self, bytes: u64, class: MemoryClass, ) -> Result<Reservation, MemoryError>

Reserves bytes of class, returning an RAII guard that releases the bytes on drop. Zero-byte reservations always succeed.

Admission rules, in order:

1. Under escalation step 1, low-priority classes are rejected (MemoryError::LowPriorityRejected).
2. The request must fit the class budget and the node limit — the configured maximum for reserved classes, the maximum minus the reserved floor for every other class, so replication/control memory is never fully starved (S1E-003 step 5).

The fast path is two atomic adds with exact rollback on rejection; no locks, no allocation.

pub fn register_reclaimable<R: Reclaimable + 'static>( &self, reclaimable: &Arc<R>, )

Registers a reclaimable subsystem (held weakly) for the governor to drive under escalation step 2. Cold path; not for hot-path use.

pub fn evict_reclaimable(&self, budget: u64) -> u64

Drives registered reclaimable subsystems until at least budget bytes have been freed (or nothing more is reclaimable), returning the bytes actually freed. The entry point of escalation step 2. Cold path.

pub fn reclaimable_bytes(&self) -> u64

Bytes currently reclaimable from registered subsystems.

pub fn request_spill_grant( &self, reservation: &mut Reservation, bytes: u64, ) -> Option<SpillGrant>

Step 3 entry point (S1E-004): while the spill trigger is active, an operator holding a Reservation of a spill-eligible class (MemoryClass::is_spill_eligible) may ask to move up to bytes of its working set to disk through crate::spill::SpillManager. On success the reservation shrinks immediately — the governor accounts the memory as freed — and the returned SpillGrant records the spilled amount; writing the bytes to spill files is charged against the query’s temporary-disk budget, and reading them back re-reserves through try_reserve. Returns None when the trigger is inactive, the class is not spill-eligible, or the reservation holds no bytes.

pub fn stats(&self) -> GovernorStats

A point-in-time snapshot of governor state.

Trait Implementations

impl Clone for MemoryGovernor

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MemoryGovernor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.