Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

feat(engine): add process-wide segment hydration budget

buger64d344c204fe
diff --git a/engine/crates/xerj-common/src/config.rs b/engine/crates/xerj-common/src/config.rs
index d7ec0fea3..9e7a91208 100644
--- a/engine/crates/xerj-common/src/config.rs
+++ b/engine/crates/xerj-common/src/config.rs
@@ -877,7 +877,7 @@ impl Default for EmbeddingConfig {
/// Resource limits.
///
-/// **10 settings.**
+/// **11 settings.**
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct LimitsConfig {
@@ -922,6 +922,12 @@ pub struct LimitsConfig {
/// `circuit_breaking_exception` instead of growing until the kernel
/// OOM-kills the process.
pub max_total_memtable_mb: u64,
+ /// Process-wide retained-payload ceiling for all immutable segment
+ /// hydration caches (default: `0` = 20% of the effective cgroup/system
+ /// memory limit). This is not an RSS ceiling: query materialization,
+ /// decode scratch, mmaps, allocator fragmentation, and unrelated caches
+ /// are outside it.
+ pub max_segment_hydration_cache_mb: u64,
/// RSS admission watermark, as a percentage of the effective process
/// memory limit (default: `95`). The effective limit is the cgroup
/// memory limit when one is set (e.g. under `systemd-run -p MemoryMax=`
@@ -953,6 +959,7 @@ impl Default for LimitsConfig {
max_mget_docs: 10_000,
max_buckets: 65_536,
max_total_memtable_mb: 0, // 0 = auto-derive (25% RAM, floor 2 GiB)
+ max_segment_hydration_cache_mb: 0, // 0 = 20% effective memory, no floor
memory_watermark_percent: 95,
disk_flood_stage_percent: 95,
}
@@ -1367,12 +1374,13 @@ mod tests {
// default_quantization, max_dimensions)
// logs: 2 (retention_days, time_partition)
// embedding: 4 (default_endpoint, default_model, batch_size, timeout_ms)
- // limits: 3 (max_query_memory_mb, max_concurrent_searches, max_fields_per_index)
+ // limits: 11 (query/concurrency/mapping/body/result/mget/bucket limits,
+ // total memtable, segment hydration cache, RSS, disk)
// indexing: 3 (turbo_batch_size, turbo_parallel, turbo_fast_analyzer)
// logging: 2 (format, access_log) ← RC4-W4 item 6
// ─────────
- // total: 50 fields, minus 1 auto-generated (admin_api_key) = 49 meaningful user settings
- let total: usize = 5 + 3 + 3 + 10 + 5 + 3 + 1 + 6 + 2 + 4 + 3 + 3 + 2;
- assert_eq!(total, 50);
+ // total: 58 fields, minus 1 auto-generated (admin_api_key) = 57 meaningful user settings
+ let total: usize = 5 + 3 + 3 + 10 + 5 + 3 + 1 + 6 + 2 + 4 + 11 + 3 + 2;
+ assert_eq!(total, 58);
}
}
diff --git a/engine/crates/xerj-engine/src/governor.rs b/engine/crates/xerj-engine/src/governor.rs
index 129fd672e..5f287be81 100644
--- a/engine/crates/xerj-engine/src/governor.rs
+++ b/engine/crates/xerj-engine/src/governor.rs
@@ -32,6 +32,8 @@ use tokio::sync::{OwnedSemaphorePermit, Semaphore};
use xerj_common::config::Config;
use xerj_common::XerjError;
+use crate::segment_cache_budget::{SegmentHydrationBudget, SegmentHydrationBudgetSnapshot};
+
/// The process-wide governor singleton.
static GOVERNOR: OnceLock<Arc<ResourceGovernor>> = OnceLock::new();
@@ -44,6 +46,9 @@ pub const SAMPLE_INTERVAL_MS: u64 = 100;
/// Process-wide resource governor. See the module docs.
pub struct ResourceGovernor {
+ /// One admission authority shared by every index in this process.
+ segment_hydration_budget: Arc<SegmentHydrationBudget>,
+ segment_hydration_budget_source: SegmentHydrationBudgetSource,
// ── item 1: process-wide memtable budget ────────────────────────────
/// Ceiling on summed memtable bytes across ALL indices. `0` = disabled.
memtable_budget_bytes: u64,
@@ -288,6 +293,8 @@ impl ResourceGovernor {
/// surfaces.
pub fn snapshot(&self) -> GovernorSnapshot {
GovernorSnapshot {
+ segment_hydration: self.segment_hydration_budget.snapshot(),
+ segment_hydration_source: self.segment_hydration_budget_source,
memtable_used_bytes: self.memtable_used_bytes.load(Ordering::Relaxed),
memtable_budget_bytes: self.memtable_budget_bytes,
memtable_tripped: self.memtable_tripped.load(Ordering::Relaxed),
@@ -303,6 +310,10 @@ impl ResourceGovernor {
search_inflight_peak: self.search_inflight_peak.load(Ordering::Relaxed),
}
}
+
+ pub fn segment_hydration_budget(&self) -> Arc<SegmentHydrationBudget> {
+ Arc::clone(&self.segment_hydration_budget)
+ }
}
/// RAII guard for a held global search permit. Decrements the in-flight
@@ -321,6 +332,8 @@ impl Drop for SearchPermit {
/// A cheap, `Copy`-able snapshot of governor state.
#[derive(Debug, Clone, Copy)]
pub struct GovernorSnapshot {
+ pub segment_hydration: SegmentHydrationBudgetSnapshot,
+ pub segment_hydration_source: SegmentHydrationBudgetSource,
pub memtable_used_bytes: u64,
pub memtable_budget_bytes: u64,
pub memtable_tripped: bool,
@@ -336,6 +349,85 @@ pub struct GovernorSnapshot {
pub search_inflight_peak: u64,
}
+#[derive(Debug, Clone, Copy, Eq, PartialEq)]
+pub enum SegmentHydrationBudgetSource {
+ Auto,
+ Config,
+ Env,
+}
+
+#[derive(Debug, Clone, Eq, PartialEq)]
+struct ResolvedSegmentHydrationBudget {
+ bytes: u64,
+ source: SegmentHydrationBudgetSource,
+ warning: Option<String>,
+}
+
+fn resolve_segment_hydration_budget(
+ effective_limit: u64,
+ configured_mb: u64,
+ env_value: Option<&str>,
+) -> ResolvedSegmentHydrationBudget {
+ const MIB: u64 = 1024 * 1024;
+ let automatic = effective_limit / 5;
+ let explicit = |mb: u64, source| {
+ let requested = mb.saturating_mul(MIB);
+ let maximum = effective_limit / 2;
+ let bytes = requested.min(maximum);
+ let warning = (requested > maximum).then(|| {
+ format!(
+ "requested segment hydration cache {} MiB exceeds 50% of effective memory; clamped to {} MiB",
+ mb,
+ bytes / MIB
+ )
+ });
+ ResolvedSegmentHydrationBudget {
+ bytes,
+ source,
+ warning,
+ }
+ };
+
+ match env_value.map(str::trim) {
+ Some("auto") => ResolvedSegmentHydrationBudget {
+ bytes: automatic,
+ source: SegmentHydrationBudgetSource::Env,
+ warning: None,
+ },
+ Some("off") => ResolvedSegmentHydrationBudget {
+ bytes: 0,
+ source: SegmentHydrationBudgetSource::Env,
+ warning: None,
+ },
+ Some(value) => match value.parse::<u64>() {
+ Ok(0) => {
+ let mut fallback =
+ resolve_segment_hydration_budget(effective_limit, configured_mb, None);
+ fallback.warning = Some(
+ "XERJ_SEGMENT_HYDRATION_CACHE_MB=0 is ambiguous; use auto or off; falling back to config"
+ .to_owned(),
+ );
+ fallback
+ }
+ Ok(mb) => explicit(mb, SegmentHydrationBudgetSource::Env),
+ Err(_) => {
+ let mut fallback =
+ resolve_segment_hydration_budget(effective_limit, configured_mb, None);
+ fallback.warning = Some(format!(
+ "invalid XERJ_SEGMENT_HYDRATION_CACHE_MB={value:?}; expected auto, off, or a positive MiB value; falling back to config"
+ ));
+ fallback
+ }
+ },
+ None if configured_mb > 0 => explicit(configured_mb, SegmentHydrationBudgetSource::Config),
+ None => ResolvedSegmentHydrationBudget {
+ bytes: automatic,
+ source: SegmentHydrationBudgetSource::Auto,
+ warning: None,
+ },
+ }
+}
+
// ─────────────────────────────────────────────────────────────────────────
// Initialisation / access
// ─────────────────────────────────────────────────────────────────────────
@@ -368,6 +460,17 @@ fn build(config: &Config) -> ResourceGovernor {
// ── RSS watermark against the effective memory limit ──
let memory_limit_bytes = effective_memory_limit_bytes();
+ let resolved_segment_hydration = resolve_segment_hydration_budget(
+ memory_limit_bytes,
+ limits.max_segment_hydration_cache_mb,
+ std::env::var("XERJ_SEGMENT_HYDRATION_CACHE_MB")
+ .ok()
+ .as_deref(),
+ );
+ if let Some(warning) = &resolved_segment_hydration.warning {
+ tracing::warn!("{warning}");
+ }
+ let segment_hydration_budget = SegmentHydrationBudget::new(resolved_segment_hydration.bytes);
let memory_watermark_bytes = if limits.memory_watermark_percent == 0 {
0
} else {
@@ -387,10 +490,14 @@ fn build(config: &Config) -> ResourceGovernor {
max_query_memory_mb = limits.max_query_memory_mb,
max_concurrent_searches,
disk_flood_pct = limits.disk_flood_stage_percent,
+ segment_hydration_cache_mb = resolved_segment_hydration.bytes / (1024 * 1024),
+ segment_hydration_cache_source = ?resolved_segment_hydration.source,
"resource governor initialised (parent circuit breaker)"
);
ResourceGovernor {
+ segment_hydration_budget,
+ segment_hydration_budget_source: resolved_segment_hydration.source,
memtable_budget_bytes,
memtable_used_bytes: AtomicU64::new(0),
memtable_tripped: AtomicBool::new(false),
@@ -612,6 +719,47 @@ fn human_bytes(b: u64) -> String {
mod tests {
use super::*;
+ #[test]
+ fn segment_hydration_resolver_is_cgroup_proportional_and_explicit() {
+ const GIB: u64 = 1024 * 1024 * 1024;
+ let auto = resolve_segment_hydration_budget(8 * GIB, 0, None);
+ assert_eq!(auto.bytes, 8 * GIB / 5);
+ assert_eq!(auto.source, SegmentHydrationBudgetSource::Auto);
+
+ let tiny = resolve_segment_hydration_budget(256 * 1024 * 1024, 0, None);
+ assert_eq!(tiny.bytes, 256 * 1024 * 1024 / 5);
+
+ let config = resolve_segment_hydration_budget(8 * GIB, 1024, None);
+ assert_eq!(config.bytes, GIB);
+ assert_eq!(config.source, SegmentHydrationBudgetSource::Config);
+
+ let off = resolve_segment_hydration_budget(8 * GIB, 1024, Some("off"));
+ assert_eq!(off.bytes, 0);
+ assert_eq!(off.source, SegmentHydrationBudgetSource::Env);
+
+ let env = resolve_segment_hydration_budget(8 * GIB, 1024, Some("2048"));
+ assert_eq!(env.bytes, 2 * GIB);
+ assert_eq!(env.source, SegmentHydrationBudgetSource::Env);
+ }
+
+ #[test]
+ fn segment_hydration_resolver_clamps_overflow_and_rejects_ambiguous_env_zero() {
+ const GIB: u64 = 1024 * 1024 * 1024;
+ let clamped = resolve_segment_hydration_budget(8 * GIB, u64::MAX, None);
+ assert_eq!(clamped.bytes, 4 * GIB);
+ assert!(clamped.warning.is_some());
+
+ let invalid = resolve_segment_hydration_budget(8 * GIB, 1024, Some("bogus"));
+ assert_eq!(invalid.bytes, GIB);
+ assert_eq!(invalid.source, SegmentHydrationBudgetSource::Config);
+ assert!(invalid.warning.is_some());
+
+ let zero = resolve_segment_hydration_budget(8 * GIB, 0, Some("0"));
+ assert_eq!(zero.bytes, 8 * GIB / 5);
+ assert_eq!(zero.source, SegmentHydrationBudgetSource::Auto);
+ assert!(zero.warning.is_some());
+ }
+
#[test]
fn effective_limit_is_positive() {
assert!(effective_memory_limit_bytes() > 0);
diff --git a/engine/crates/xerj-engine/src/ingest_memory.rs b/engine/crates/xerj-engine/src/ingest_memory.rs
index 5f2a06c12..33461c8dd 100644
--- a/engine/crates/xerj-engine/src/ingest_memory.rs
+++ b/engine/crates/xerj-engine/src/ingest_memory.rs
@@ -234,6 +234,10 @@ pub struct Event {
/// Sum of all logical category currents in this coherent snapshot.
/// This is diagnostic attribution, not an allocator/RSS identity.
pub logical_total_current: u64,
+ /// Process-wide retained segment-hydration payload/key ceiling. Separate
+ /// from logical ingest ownership and explicitly not an RSS identity.
+ pub segment_hydration_cache:
+ Option<crate::segment_cache_budget::SegmentHydrationBudgetSnapshot>,
/// Retain/release underflows observed since process start.
pub accounting_errors: u64,
/// Trace events rejected by the bounded output sink since trace start.
@@ -429,6 +433,8 @@ impl Ledger {
scope,
logical,
logical_total_current,
+ segment_hydration_cache: crate::governor::global()
+ .map(|governor| governor.snapshot().segment_hydration),
accounting_errors: self.accounting_errors.load(Ordering::Relaxed),
dropped_events: self.dropped_events.load(Ordering::Relaxed),
allocator: AllocatorSnapshot {
@@ -483,7 +489,14 @@ fn measurement(category: Category) -> Measurement {
Category::MemtableActive
| Category::ParsedSource
| Category::PreparedDocument
- | Category::FlushDrained => Measurement::Estimated,
+ | Category::FlushDrained
+ | Category::CacheStoredSlices
+ | Category::CacheDocValues
+ | Category::CacheStoredValues
+ | Category::CacheSortShadow
+ | Category::CacheIdPositions
+ | Category::CacheRowSequences
+ | Category::CacheDecodedStored => Measurement::Estimated,
_ => Measurement::Unavailable,
}
}
diff --git a/engine/crates/xerj-engine/src/lib.rs b/engine/crates/xerj-engine/src/lib.rs
index 52b252f59..06d9c0711 100644
--- a/engine/crates/xerj-engine/src/lib.rs
+++ b/engine/crates/xerj-engine/src/lib.rs
@@ -26,6 +26,7 @@ pub mod ingest_memory;
pub mod memtable;
pub mod painless;
pub mod rbac;
+pub mod segment_cache_budget;
pub mod segment_cache_estimates;
pub mod slow_query;
pub mod sql;
diff --git a/engine/crates/xerj-engine/src/segment_cache_budget.rs b/engine/crates/xerj-engine/src/segment_cache_budget.rs
new file mode 100644
index 000000000..dec0a3b97
--- /dev/null
+++ b/engine/crates/xerj-engine/src/segment_cache_budget.rs
@@ -0,0 +1,388 @@
+//! Process-wide retained-payload budget for immutable segment hydration caches.
+//!
+//! This is deliberately not an RSS limit: allocator fragmentation, DashMap
+//! capacity, mmaps, query-owned materialization, and decode scratch live
+//! outside this accounting. A charge follows the cached value through every
+//! in-flight reader and is refunded only when its last `Arc` is dropped.
+
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+
+use crate::ingest_memory::{Category, Retained};
+
+pub const CATEGORY_COUNT: usize = 7;
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[repr(usize)]
+pub enum SegmentCacheCategory {
+ StoredSlices = 0,
+ DocValues,
+ StoredValues,
+ SortShadow,
+ IdPositions,
+ RowSequences,
+ DecodedStored,
+}
+
+impl SegmentCacheCategory {
+ pub const ALL: [Self; CATEGORY_COUNT] = [
+ Self::StoredSlices,
+ Self::DocValues,
+ Self::StoredValues,
+ Self::SortShadow,
+ Self::IdPositions,
+ Self::RowSequences,
+ Self::DecodedStored,
+ ];
+
+ fn trace_category(self) -> Category {
+ match self {
+ Self::StoredSlices => Category::CacheStoredSlices,
+ Self::DocValues => Category::CacheDocValues,
+ Self::StoredValues => Category::CacheStoredValues,
+ Self::SortShadow => Category::CacheSortShadow,
+ Self::IdPositions => Category::CacheIdPositions,
+ Self::RowSequences => Category::CacheRowSequences,
+ Self::DecodedStored => Category::CacheDecodedStored,
+ }
+ }
+}
+
+#[derive(Debug, Clone, Copy, Eq, PartialEq, serde::Serialize)]
+pub struct SegmentHydrationBudgetSnapshot {
+ pub limit: u64,
+ pub current: u64,
+ pub peak: u64,
+ pub refused: u64,
+ pub accounting_errors: u64,
+ pub category_current: [u64; CATEGORY_COUNT],
+ pub category_peak: [u64; CATEGORY_COUNT],
+}
+
+pub struct SegmentHydrationBudget {
+ limit: u64,
+ used: AtomicU64,
+ peak: AtomicU64,
+ refused: AtomicU64,
+ accounting_errors: AtomicU64,
+ category_current: [AtomicU64; CATEGORY_COUNT],
+ category_peak: [AtomicU64; CATEGORY_COUNT],
+}
+
+impl SegmentHydrationBudget {
+ pub fn new(limit: u64) -> Arc<Self> {
+ Arc::new(Self {
+ limit,
+ used: AtomicU64::new(0),
+ peak: AtomicU64::new(0),
+ refused: AtomicU64::new(0),
+ accounting_errors: AtomicU64::new(0),
+ category_current: std::array::from_fn(|_| AtomicU64::new(0)),
+ category_peak: std::array::from_fn(|_| AtomicU64::new(0)),
+ })
+ }
+
+ pub fn limit(&self) -> u64 {
+ self.limit
+ }
+
+ pub fn try_charge(
+ self: &Arc<Self>,
+ category: SegmentCacheCategory,
+ bytes: u64,
+ ) -> Option<BudgetCharge> {
+ let mut current = self.used.load(Ordering::Acquire);
+ loop {
+ let Some(next) = current.checked_add(bytes) else {
+ self.refused.fetch_add(1, Ordering::Relaxed);
+ return None;
+ };
+ if next > self.limit {
+ self.refused.fetch_add(1, Ordering::Relaxed);
+ return None;
+ }
+ match self.used.compare_exchange_weak(
+ current,
+ next,
+ Ordering::AcqRel,
+ Ordering::Acquire,
+ ) {
+ Ok(_) => {
+ self.peak.fetch_max(next, Ordering::Relaxed);
+ let category_current = self.category_current[category as usize]
+ .fetch_add(bytes, Ordering::AcqRel)
+ + bytes;
+ self.category_peak[category as usize]
+ .fetch_max(category_current, Ordering::Relaxed);
+ return Some(BudgetCharge {
+ budget: Arc::clone(self),
+ category,
+ bytes,
+ });
+ }
+ Err(observed) => current = observed,
+ }
+ }
+ }
+
+ pub fn snapshot(&self) -> SegmentHydrationBudgetSnapshot {
+ SegmentHydrationBudgetSnapshot {
+ limit: self.limit,
+ current: self.used.load(Ordering::Acquire),
+ peak: self.peak.load(Ordering::Acquire),
+ refused: self.refused.load(Ordering::Acquire),
+ accounting_errors: self.accounting_errors.load(Ordering::Acquire),
+ category_current: std::array::from_fn(|i| {
+ self.category_current[i].load(Ordering::Acquire)
+ }),
+ category_peak: std::array::from_fn(|i| self.category_peak[i].load(Ordering::Acquire)),
+ }
+ }
+
+ fn release(&self, category: SegmentCacheCategory, bytes: u64) {
+ checked_sub(
+ &self.category_current[category as usize],
+ bytes,
+ &self.accounting_errors,
+ );
+ checked_sub(&self.used, bytes, &self.accounting_errors);
+ }
+}
+
+fn checked_sub(counter: &AtomicU64, bytes: u64, errors: &AtomicU64) {
+ let result = counter.fetch_update(Ordering::AcqRel, Ordering::Acquire, |current| {
+ current.checked_sub(bytes)
+ });
+ if result.is_err() {
+ errors.fetch_add(1, Ordering::Relaxed);
+ debug_assert!(false, "segment hydration cache accounting underflow");
+ }
+}
+
+pub struct BudgetCharge {
+ budget: Arc<SegmentHydrationBudget>,
+ category: SegmentCacheCategory,
+ bytes: u64,
+}
+
+impl Drop for BudgetCharge {
+ fn drop(&mut self) {
+ self.budget.release(self.category, self.bytes);
+ }
+}
+
+pub struct CacheResident<T> {
+ value: T,
+ _charge: Option<BudgetCharge>,
+ _trace_retained: Retained<'static>,
+}
+
+impl<T> CacheResident<T> {
+ pub fn admitted(
+ value: T,
+ charge: BudgetCharge,
+ category: SegmentCacheCategory,
+ bytes: u64,
+ ) -> Arc<Self> {
+ Arc::new(Self {
+ value,
+ _charge: Some(charge),
+ _trace_retained: Retained::new(
+ category.trace_category(),
+ usize::try_from(bytes).unwrap_or(usize::MAX),
+ ),
+ })
+ }
+
+ pub fn uncached(value: T) -> Arc<Self> {
+ Arc::new(Self {
+ value,
+ _charge: None,
+ _trace_retained: Retained::disabled(),
+ })
+ }
+
+ pub fn value(&self) -> &T {
+ &self.value
+ }
+}
+
+impl<T> std::ops::Deref for CacheResident<T> {
+ type Target = T;
+
+ fn deref(&self) -> &Self::Target {
+ &self.value
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn charge_is_refunded_only_after_last_arc() {
+ let budget = SegmentHydrationBudget::new(64);
+ let charge = budget
+ .try_charge(SegmentCacheCategory::StoredValues, 40)
+ .unwrap();
+ let resident =
+ CacheResident::admitted(vec![1_u8], charge, SegmentCacheCategory::StoredValues, 40);
+ let reader = Arc::clone(&resident);
+ drop(resident);
+ assert_eq!(budget.snapshot().current, 40);
+ drop(reader);
+ assert_eq!(budget.snapshot().current, 0);
+ }
+
+ #[test]
+ fn zero_limit_overflow_and_categories_are_exact() {
+ let off = SegmentHydrationBudget::new(0);
+ assert!(off
+ .try_charge(SegmentCacheCategory::StoredSlices, 1)
+ .is_none());
+ let budget = SegmentHydrationBudget::new(u64::MAX);
+ let charge = budget
+ .try_charge(SegmentCacheCategory::DocValues, u64::MAX)
+ .unwrap();
+ assert!(budget
+ .try_charge(SegmentCacheCategory::RowSequences, 1)
+ .is_none());
+ let snapshot = budget.snapshot();
+ assert_eq!(snapshot.current, u64::MAX);
+ assert_eq!(
+ snapshot.category_current[SegmentCacheCategory::DocValues as usize],
+ u64::MAX
+ );
+ assert_eq!(snapshot.refused, 1);
+ drop(charge);
+ assert_eq!(budget.snapshot().current, 0);
+ }
+
+ #[test]
+ fn underflow_is_detected_without_wrapping_the_counter() {
+ let budget = SegmentHydrationBudget::new(16);
+ let charge = budget
+ .try_charge(SegmentCacheCategory::RowSequences, 8)
+ .unwrap();
+ drop(charge);
+ let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+ budget.release(SegmentCacheCategory::RowSequences, 8);
+ }));
+ assert!(result.is_err(), "debug builds must surface double release");
+ let snapshot = budget.snapshot();
+ assert_eq!(snapshot.current, 0);
+ assert_eq!(snapshot.accounting_errors, 1);
+ }
+
+ #[test]
+ fn concurrent_cas_never_exceeds_limit() {
+ let budget = SegmentHydrationBudget::new(1_000);
+ let barrier = Arc::new(std::sync::Barrier::new(65));
+ let mut threads = Vec::new();
+ for _ in 0..64 {
+ let budget = Arc::clone(&budget);
+ let barrier = Arc::clone(&barrier);
+ threads.push(std::thread::spawn(move || {
+ barrier.wait();
+ budget.try_charge(SegmentCacheCategory::DecodedStored, 31)
+ }));
+ }
+ barrier.wait();
+ let charges: Vec<_> = threads
+ .into_iter()
+ .filter_map(|thread| thread.join().unwrap())
+ .collect();
+ let snapshot = budget.snapshot();
+ assert!(snapshot.current <= 1_000);
+ assert!(snapshot.peak <= 1_000);
+ assert_eq!(snapshot.current, charges.len() as u64 * 31);
+ drop(charges);
+ assert_eq!(budget.snapshot().current, 0);
+ }
+
+ #[test]
+ fn refusal_can_return_an_uncharged_correct_local_value() {
+ let budget = SegmentHydrationBudget::new(1);
+ assert!(budget
+ .try_charge(SegmentCacheCategory::StoredValues, 2)
+ .is_none());
+ let local = CacheResident::uncached(vec![String::from("answer")]);
+ assert_eq!(local[0], "answer");
+ let snapshot = budget.snapshot();
+ assert_eq!(snapshot.current, 0);
+ assert_eq!(snapshot.refused, 1);
+ }
+
+ #[test]
+ fn retirement_refunds_only_after_held_reader_drops() {
+ let budget = SegmentHydrationBudget::new(128);
+ let map = dashmap::DashMap::<String, Arc<CacheResident<Vec<u8>>>>::new();
+ let charge = budget
+ .try_charge(SegmentCacheCategory::DecodedStored, 80)
+ .unwrap();
+ let resident =
+ CacheResident::admitted(vec![7], charge, SegmentCacheCategory::DecodedStored, 80);
+ map.insert("retired".into(), Arc::clone(&resident));
+ let reader = Arc::clone(&resident);
+ drop(resident);
+ map.remove("retired");
+ assert_eq!(budget.snapshot().current, 80);
+ drop(reader);
+ assert_eq!(budget.snapshot().current, 0);
+ }
+
+ #[test]
+ fn two_index_maps_share_one_ceiling() {
+ let budget = SegmentHydrationBudget::new(100);
+ let first = dashmap::DashMap::<String, Arc<CacheResident<Vec<u8>>>>::new();
+ let second = dashmap::DashMap::<String, Arc<CacheResident<Vec<u8>>>>::new();
+ let charge = budget
+ .try_charge(SegmentCacheCategory::StoredSlices, 60)
+ .unwrap();
+ first.insert(
+ "a".into(),
+ CacheResident::admitted(vec![1], charge, SegmentCacheCategory::StoredSlices, 60),
+ );
+ assert!(budget
+ .try_charge(SegmentCacheCategory::DocValues, 60)
+ .is_none());
+ assert!(second.is_empty());
+ assert_eq!(budget.snapshot().peak, 60);
+ drop(first);
+ assert_eq!(budget.snapshot().current, 0);
+ }
+
+ #[tokio::test]
+ async fn telemetry_categories_match_budget_and_release_to_zero() {
+ let ledger = Box::leak(Box::new(crate::ingest_memory::Ledger::new()));
+ crate::ingest_memory::with_test_ledger(ledger, async {
+ let budget = SegmentHydrationBudget::new(1_000);
+ for category in SegmentCacheCategory::ALL {
+ let charge = budget.try_charge(category, 17).unwrap();
+ let resident = CacheResident::admitted(vec![1_u8], charge, category, 17);
+ assert_eq!(
+ ledger
+ .gauge(
+ category.trace_category(),
+ crate::ingest_memory::Measurement::Estimated,
+ )
+ .current,
+ 17
+ );
+ assert_eq!(budget.snapshot().category_current[category as usize], 17);
+ drop(resident);
+ assert_eq!(
+ ledger
+ .gauge(
+ category.trace_category(),
+ crate::ingest_memory::Measurement::Estimated,
+ )
+ .current,
+ 0
+ );
+ }
+ assert_eq!(budget.snapshot().current, 0);
+ })
+ .await;
+ }
+}
diff --git a/engine/xerj.default.toml b/engine/xerj.default.toml
index cff373334..f502f3bb2 100644
--- a/engine/xerj.default.toml
+++ b/engine/xerj.default.toml
@@ -287,7 +287,7 @@ batch_size = 64
# request fails with a timeout error.
timeout_ms = 5000
-# ── Resource Limits (3 settings) ──────────────────────────────────────────────
+# ── Resource Limits (11 settings; omitted keys use documented defaults) ───────
[limits]
@@ -306,6 +306,12 @@ max_concurrent_searches = 64
# Elasticsearch uses 1000 as its default; 500 is intentionally stricter.
max_fields_per_index = 500
+# Process-wide retained-payload budget for the seven immutable segment
+# hydration caches (MiB). 0 derives 20% of the effective cgroup/system memory
+# limit with no minimum floor. This is not an RSS limit: query-owned results,
+# decode scratch, mmaps, allocator fragmentation, and other caches are separate.
+max_segment_hydration_cache_mb = 0
+
# ── Turbo Indexing (3 settings) — opt-in high-throughput mode ─────────────────
#
# Turbo mode is enabled per-request, not globally: