Struct MemoryGovernor 

pub struct MemoryGovernor { /* private fields */ }

The central memory governor.

Thread-safe: global, database, and tenant counters use atomics. The budget map itself is behind an RwLock; reads (common) take a shared lock, writes (rare — only when quotas change) take an exclusive lock.

Implementations

impl MemoryGovernor

pub fn reserve( self: &Arc<Self>, engine: EngineId, bytes: usize, ) -> Result<BudgetGuard>

Reserve bytes for engine and return a BudgetGuard that releases them on drop.

Errors

Returns MemError::BudgetExhausted or MemError::GlobalCeilingExceeded if the reservation would exceed any configured limit. Returns MemError::UnknownEngine if engine is not registered.

impl MemoryGovernor

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

Create a new governor with the given configuration.

pub fn set_database_budget(&self, db: DatabaseId, max_bytes: usize)

Install or replace the memory ceiling for a database.

Called by the catalog apply path when ALTER DATABASE … SET QUOTA is executed. Takes effect for all subsequent try_reserve calls; in-flight tokens already issued are not recalled.

pub fn clear_database_budget(&self, db: DatabaseId)

Remove the per-database budget ceiling, making that database uncapped.

pub fn set_tenant_budget( &self, db: DatabaseId, tenant: TenantId, max_bytes: usize, )

Install or replace the memory ceiling for a tenant within a database.

pub fn clear_tenant_budget(&self, db: DatabaseId, tenant: TenantId)

Remove the per-tenant budget ceiling.

pub fn try_reserve( &self, db: DatabaseId, tenant: TenantId, engine: EngineId, size: usize, ) -> Result<ReservationToken>

Reserve size bytes for the given (database, tenant, engine) triple.

Check order: global → database → tenant → engine (largest scope first, to fail fast and avoid partial increments at deep levels).

On any failure the function rolls back any partial increments already applied at higher layers and returns an error describing the exhausted layer. On success, returns a ReservationToken whose Drop implementation releases all four layers.

Databases or tenants without a configured budget are skipped (uncapped). Engines without a configured budget return MemError::UnknownEngine.

pub fn release(&self, engine: EngineId, size: usize)

Release size bytes back to the given engine’s budget.

This method only releases the engine-layer counter; it exists for legacy compatibility with code that uses [BudgetGuard] rather than ReservationToken. New code should hold a ReservationToken and let drop handle all four layers.

pub fn budget(&self, engine: EngineId) -> Option<&Budget>

Get the budget for a specific engine.

pub fn global_ceiling(&self) -> usize

Get the global ceiling.

pub fn total_allocated(&self) -> usize

Total memory allocated across all engines (engine-layer sum).

pub fn total_over_release_count(&self) -> usize

Total number of over-release events observed across all per-engine budgets. A non-zero value signals at least one call-site is releasing more bytes than it reserved — the “memory release exceeds allocation” warning class. Per-engine allocated() saturates to zero on over-release, so this counter is the only post-hoc observable for the bug.

pub fn global_utilization_percent(&self) -> u8

Global utilization as a percentage (0-100). Computed in u128 so a corrupted engine-layer sum clamps to 100 % instead of overflowing.

pub fn engine_pressure(&self, engine: EngineId) -> PressureLevel

Current pressure level for a specific engine.

pub fn global_pressure(&self) -> PressureLevel

Current global pressure level.

pub fn worst_engine_pressure(&self) -> PressureLevel

Worst-case (highest) pressure level across every engine that has a configured budget. Cheap: iterates the in-memory budget map and allocates nothing — meant to be called once per Data-Plane core-loop tick, unlike snapshot which materialises a Vec. Returns Normal when no engine budgets are configured.

pub fn set_thresholds(&mut self, thresholds: PressureThresholds)

Set custom pressure thresholds.

pub fn snapshot(&self) -> Vec<EngineSnapshot>

Snapshot of all engine budget states (for metrics/debugging).

Trait Implementations

impl Debug for MemoryGovernor

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

Formats the value using the given formatter.