use std::time::{Duration, Instant};
use super::admission::ReservationQueueDiagnosticSample;
use super::arena::ArenaDiagnosticSnapshot;
use super::maintenance::MaintenanceDiagnosticSnapshot;
use super::metrics::MemoryMetrics;
use super::PoolInner;
pub(super) struct PeriodicDiagnosticReporter {
interval: Duration,
next_snapshot: Instant,
previous: PoolDiagnosticSnapshot,
}
impl PeriodicDiagnosticReporter {
pub(super) fn new(pool: &PoolInner, interval: Duration) -> Option<Self> {
let previous = PoolDiagnosticSnapshot::capture(pool);
let Some(next_snapshot) = next_snapshot_after(previous.captured_at, interval) else {
warn_unrepresentable_deadline(interval);
return None;
};
Some(Self {
interval,
next_snapshot,
previous,
})
}
pub(super) fn next_snapshot(&self) -> Instant {
self.next_snapshot
}
pub(super) fn emit(&mut self, pool: &PoolInner) {
let current = PoolDiagnosticSnapshot::capture(pool);
emit_snapshot(¤t, &self.previous, self.interval);
self.previous = current;
}
pub(super) fn schedule_next(&mut self, completed_at: Instant) -> bool {
let Some(next_snapshot) = next_snapshot_after(completed_at, self.interval) else {
warn_unrepresentable_deadline(self.interval);
return false;
};
self.next_snapshot = next_snapshot;
true
}
}
fn warn_unrepresentable_deadline(interval: Duration) {
tracing::warn!(
target: crate::telemetry::TARGET_MEMORY,
configured_interval_ms = interval.as_millis(),
"disabled buffer-pool diagnostic snapshots with an unrepresentable deadline"
);
}
fn next_snapshot_after(now: Instant, interval: Duration) -> Option<Instant> {
now.checked_add(interval)
}
struct PoolDiagnosticSnapshot {
captured_at: Instant,
memory: MemoryMetrics,
queue: ReservationQueueDiagnosticSample,
arena: ArenaDiagnosticSnapshot,
maintenance: MaintenanceDiagnosticSnapshot,
}
impl PoolDiagnosticSnapshot {
fn capture(pool: &PoolInner) -> Self {
let captured_at = Instant::now();
let (memory, queue) = pool.diagnostic_memory_sample(captured_at);
let arena = pool.arena.diagnostics();
let maintenance = pool.maintenance.diagnostics();
Self {
captured_at,
memory,
queue,
arena,
maintenance,
}
}
}
struct PoolDiagnosticDelta {
reservation_enqueues: u64,
optimistic_scans: u64,
optimistic_scan_words: u64,
optimistic_misses: u64,
serialized_fallbacks: u64,
serialized_slots_inspected: u64,
blocks_prepared: u64,
block_ranges_reserved: u64,
rolled_back_carriers: u64,
trim_slots_scanned: u64,
blocks_reclaimed: u64,
cleanup_retries: u64,
cleanup_failures: u64,
idle_deadlines: u64,
reclaim_passes: u64,
reclaim_retries: u64,
cleanup_requests: u64,
}
impl PoolDiagnosticDelta {
fn between(current: &PoolDiagnosticSnapshot, previous: &PoolDiagnosticSnapshot) -> Self {
let (optimistic_scans, optimistic_scan_words) =
match (current.arena.detailed, previous.arena.detailed) {
(Some(current), Some(previous)) => (
counter_delta(current.optimistic_scans, previous.optimistic_scans),
counter_delta(
current.optimistic_scan_words,
previous.optimistic_scan_words,
),
),
_ => (0, 0),
};
Self {
reservation_enqueues: counter_delta(
current.memory.waits_total(),
previous.memory.waits_total(),
),
optimistic_scans,
optimistic_scan_words,
optimistic_misses: counter_delta(
current.arena.optimistic_misses,
previous.arena.optimistic_misses,
),
serialized_fallbacks: counter_delta(
current.arena.serialized_fallbacks,
previous.arena.serialized_fallbacks,
),
serialized_slots_inspected: counter_delta(
current.arena.serialized_slots_inspected,
previous.arena.serialized_slots_inspected,
),
blocks_prepared: counter_delta(
current.arena.blocks_prepared,
previous.arena.blocks_prepared,
),
block_ranges_reserved: counter_delta(
current.arena.block_ranges_reserved,
previous.arena.block_ranges_reserved,
),
rolled_back_carriers: counter_delta(
current.arena.rolled_back_carriers,
previous.arena.rolled_back_carriers,
),
trim_slots_scanned: counter_delta(
current.arena.trim_slots_scanned,
previous.arena.trim_slots_scanned,
),
blocks_reclaimed: counter_delta(
current.arena.blocks_reclaimed,
previous.arena.blocks_reclaimed,
),
cleanup_retries: counter_delta(
current.arena.cleanup_retries,
previous.arena.cleanup_retries,
),
cleanup_failures: counter_delta(
current.arena.cleanup_failures,
previous.arena.cleanup_failures,
),
idle_deadlines: counter_delta(
current.maintenance.idle_deadlines,
previous.maintenance.idle_deadlines,
),
reclaim_passes: counter_delta(
current.maintenance.reclaim_passes,
previous.maintenance.reclaim_passes,
),
reclaim_retries: counter_delta(
current.maintenance.reclaim_retries,
previous.maintenance.reclaim_retries,
),
cleanup_requests: counter_delta(
current.maintenance.cleanup_requests,
previous.maintenance.cleanup_requests,
),
}
}
}
fn counter_delta(current: u64, previous: u64) -> u64 {
current.saturating_sub(previous)
}
fn emit_snapshot(
current: &PoolDiagnosticSnapshot,
previous: &PoolDiagnosticSnapshot,
interval: Duration,
) {
let delta = PoolDiagnosticDelta::between(current, previous);
let elapsed = current
.captured_at
.saturating_duration_since(previous.captured_at);
let detailed_allocator_enabled = current.arena.detailed.is_some();
let (optimistic_scans, optimistic_scan_words) = current
.arena
.detailed
.map(|detailed| (detailed.optimistic_scans, detailed.optimistic_scan_words))
.unwrap_or((0, 0));
tracing::debug!(
target: crate::telemetry::TARGET_MEMORY,
configured_interval_ms = interval.as_millis(),
elapsed_ms = elapsed.as_millis(),
configured_capacity_bytes = current.memory.capacity_bytes(),
admission_used_bytes = current.memory.admitted_bytes(),
admission_overage_bytes = current.memory.admission_overage_bytes(),
active_planned_demand_bytes = current.memory.active_planned_demand_bytes(),
charged_capacity_bytes = current.memory.in_use_bytes(),
prepared_capacity_bytes = current.memory.prepared_capacity_bytes(),
queued_reservations = current.memory.waiting_requests(),
queued_reservations_peak = current.queue.peak_depth,
reservation_enqueues_total = current.memory.waits_total(),
reservation_enqueues_delta = delta.reservation_enqueues,
reservation_queue_nonempty = current.queue.current_depth != 0,
reservation_queue_nonempty_duration_ms =
current.queue.nonempty_duration.as_millis(),
reservation_queue_continuous_nonempty_ms = current
.queue
.continuous_nonempty_duration
.map(|duration| duration.as_millis())
.unwrap_or(0),
detailed_allocator_enabled,
optimistic_scans_total = optimistic_scans,
optimistic_scans_delta = delta.optimistic_scans,
optimistic_scan_words_total = optimistic_scan_words,
optimistic_scan_words_delta = delta.optimistic_scan_words,
optimistic_misses_total = current.arena.optimistic_misses,
optimistic_misses_delta = delta.optimistic_misses,
serialized_fallbacks_total = current.arena.serialized_fallbacks,
serialized_fallbacks_delta = delta.serialized_fallbacks,
serialized_slots_inspected_total = current.arena.serialized_slots_inspected,
serialized_slots_inspected_delta = delta.serialized_slots_inspected,
blocks_prepared_total = current.arena.blocks_prepared,
blocks_prepared_delta = delta.blocks_prepared,
block_ranges_reserved_total = current.arena.block_ranges_reserved,
block_ranges_reserved_delta = delta.block_ranges_reserved,
rolled_back_carriers_total = current.arena.rolled_back_carriers,
rolled_back_carriers_delta = delta.rolled_back_carriers,
trim_slots_scanned_total = current.arena.trim_slots_scanned,
trim_slots_scanned_delta = delta.trim_slots_scanned,
blocks_reclaimed_total = current.arena.blocks_reclaimed,
blocks_reclaimed_delta = delta.blocks_reclaimed,
cleanup_retries_total = current.arena.cleanup_retries,
cleanup_retries_delta = delta.cleanup_retries,
cleanup_failures_total = current.arena.cleanup_failures,
cleanup_failures_delta = delta.cleanup_failures,
idle_deadlines_total = current.maintenance.idle_deadlines,
idle_deadlines_delta = delta.idle_deadlines,
reclaim_passes_total = current.maintenance.reclaim_passes,
reclaim_passes_delta = delta.reclaim_passes,
reclaim_retries_total = current.maintenance.reclaim_retries,
reclaim_retries_delta = delta.reclaim_retries,
cleanup_requests_total = current.maintenance.cleanup_requests,
cleanup_requests_delta = delta.cleanup_requests,
maintenance_disabled = current.maintenance.maintenance_disabled,
"buffer-pool diagnostic snapshot"
);
}
#[cfg(test)]
mod tests {
use futures_test::task::new_count_waker;
use super::super::test_util::{poll_reserve, test_pool, test_pool_with_scan_and_diagnostics};
use super::*;
use crate::config::MemoryDiagnosticsConfig;
#[test]
fn default_pool_omits_detailed_scans_but_keeps_pressure_counters() {
let (pool, carrier_size) =
test_pool_with_scan_and_diagnostics(1, 3, 1, MemoryDiagnosticsConfig::default());
let reservation = pool
.try_reserve(carrier_size * 3)
.unwrap()
.expect("reservation");
let acquired = pool.acquire(&reservation, carrier_size * 3).unwrap();
let diagnostics = pool.diagnostics();
assert_eq!(diagnostics.detailed_allocator, None);
assert!(diagnostics.optimistic_misses > 0);
assert!(diagnostics.serialized_fallbacks > 0);
drop(acquired);
}
#[test]
fn baseline_reporter_does_not_require_detailed_counters() {
let (pool, _) =
test_pool_with_scan_and_diagnostics(1, 1, 1, MemoryDiagnosticsConfig::default());
let mut reporter = PeriodicDiagnosticReporter::new(&pool.inner, Duration::from_secs(1))
.expect("baseline diagnostic reporter");
reporter.emit(&pool.inner);
assert!(reporter.previous.arena.detailed.is_none());
}
#[test]
fn reporter_arms_one_complete_interval_from_its_baseline() {
let (pool, _) = test_pool(1, 1);
let interval = Duration::from_secs(1);
let reporter =
PeriodicDiagnosticReporter::new(&pool.inner, interval).expect("diagnostic reporter");
assert_eq!(
reporter
.next_snapshot()
.saturating_duration_since(reporter.previous.captured_at),
interval
);
}
#[test]
fn queue_snapshots_follow_enqueue_cancel_and_grant() {
let (pool, carrier_size) = test_pool(1, 1);
let holder = pool.try_reserve(carrier_size).unwrap().unwrap();
let (waker, _) = new_count_waker();
let mut cancelled = pool.reserve(carrier_size);
let mut granted = pool.reserve(carrier_size);
assert!(poll_reserve(&mut cancelled, &waker).is_pending());
assert!(poll_reserve(&mut granted, &waker).is_pending());
let (_, queued) = pool.inner.diagnostic_memory_sample(Instant::now());
assert_eq!(queued.current_depth, 2);
assert_eq!(queued.peak_depth, 2);
assert!(queued.continuous_nonempty_duration.is_some());
drop(cancelled);
drop(holder);
let (_, cleared) = pool.inner.diagnostic_memory_sample(Instant::now());
assert_eq!(cleared.current_depth, 0);
assert_eq!(cleared.peak_depth, 2);
assert_eq!(cleared.continuous_nonempty_duration, None);
drop(granted);
}
#[test]
fn cumulative_counter_delta_never_wraps() {
assert_eq!(counter_delta(12, 5), 7);
assert_eq!(counter_delta(5, 12), 0);
}
}