Crate memory_budget 

memory-budget

Adaptive process-memory budgeting for applications with bounded caches.

memory-budget coordinates caches and other memory reporters under a target resident-set size. It samples process RSS, applies a pluggable policy, and adjusts registered cache ceilings. A Tokio task can drive the periodic ticks; the policy itself is synchronous and deterministic, which keeps it easy to test.

Core model

• Resizable is the small contract implemented by an adjustable cache.
• NonCacheReporter accounts for memory that cannot be resized by the budget.
• MemoryBudget owns weak registrations, leases, RSS sampling, and ticks.
• Policy decides new cache ceilings from the latest bounded snapshot.
• RssSource and JemallocStatsSource isolate platform and allocator data.

The budget does not own cache entries, queue work, or payloads. It only coordinates the explicit byte measurements supplied by its participants.

Example

use std::sync::Arc;

use memory_budget::{
    BudgetConfig,
    MemoryBudget,
    Resizable,
};

#[tokio::main(flavor = "current_thread")]
async fn main() {
    let budget = Arc::new(MemoryBudget::new(BudgetConfig::new(512 * 1024 * 1024)));
    let cache: Arc<dyn Resizable> = Arc::new(MyCache::default());
    budget.register(&cache);
    let _tick = budget.spawn();
}

Environment configuration

BudgetConfig::from_env reads these variables:

Variable	Meaning
MEMORY_BUDGET_TARGET_MIB	Soft RSS target; otherwise derived from system RAM
MEMORY_BUDGET_TICK_SECS	Tick interval, default 5 seconds
MEMORY_BUDGET_HARD_CEILING_MIB	Optional hard process ceiling

Use BudgetConfig::new when configuration must be supplied explicitly.

Optional jemalloc support

Enable the jemalloc feature to expose SystemJemallocStats backed by tikv-jemalloc-ctl. The heap-profiling feature adds threshold-driven prof.dump diagnostics for applications built with jemalloc profiling.

License

Licensed under either of:

• Apache License, Version 2.0
• MIT License

at your option.

Modules

policy

Reapportionment policies for MemoryBudget.

Structs

AtomicReporter

A NonCacheReporter backed by a shared atomic gauge.

BudgetConfig

Knobs that govern a MemoryBudget instance.

BudgetSnapshot

Diagnostic snapshot of one budget tick.

CacheSnapshot

Per-cache slice of a BudgetSnapshot.

GaugeGuard

RAII guard that publishes a fixed byte count to a MemoryGauge for its lifetime. Created by MemoryGauge::guard; Drop removes the contribution again.

JemallocStats

Snapshot of jemalloc’s process-wide accounting at one tick. All values are bytes. Definitions match the stats.* mallctl namespace (see jemalloc(3)).

LeaseGuard

Active short-term reservation against the budget.

MemoryBudget

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

MemoryGauge

Producer-side handle to an AtomicReporter’s gauge.

NoJemallocStats

No-op source used when the binary does not install jemalloc as the global allocator. All readings are zero, which the tick log distinguishes from real-but-tiny readings via the surrounding cache_bytes_current / rss_bytes context.

ReporterSnapshot

Per-reporter slice of a BudgetSnapshot.

ResizableStats

Point-in-time stats sample from a registered cache.

SystemRss

Live RSS reader backed by sysinfo.

Traits

JemallocStatsSource

“What does jemalloc say about our memory usage right now?”

NonCacheReporter

A subsystem that reports its current non-cache memory footprint.

Resizable

Minimal interface a memory-budget-aware cache must expose.

RssSource

Abstraction over “what is the current process RSS, in bytes”.