santh-bufpool 0.1.0

use std::sync::atomic::{AtomicUsize, Ordering};

/// Pool statistics for observability.
///
/// All counters use relaxed atomics and are safe to read from any thread.
///
/// # Example
///
/// ```rust
/// use santh_bufpool::{BufferPool, PoolConfig};
///
/// let pool = BufferPool::new(PoolConfig::default());
/// let buf = pool.checkout(64).unwrap();
/// let stats = pool.stats().snapshot();
/// assert_eq!(stats.checked_out, 1);
/// drop(buf);
/// ```
#[derive(Debug, Default)]
pub struct PoolStats {
    /// Number of successful checkouts from the pool (reuse).
    pub hits: AtomicUsize,
    /// Number of fallback allocations (pool exhausted).
    pub misses: AtomicUsize,
    /// Number of buffers currently checked out.
    pub checked_out: AtomicUsize,
    /// Peak simultaneous checkouts observed.
    pub peak_checked_out: AtomicUsize,
    /// Total bytes currently checked out (sum of requested sizes).
    pub bytes_checked_out: AtomicUsize,
    /// Peak bytes checked out simultaneously.
    pub peak_bytes_checked_out: AtomicUsize,
}

impl PoolStats {
    /// Snapshot the current stats.
    ///
    /// # Example
    ///
    /// ```rust
    /// use santh_bufpool::{BufferPool, PoolConfig};
    ///
    /// let pool = BufferPool::new(PoolConfig::default());
    /// let snapshot = pool.stats().snapshot();
    /// assert_eq!(snapshot.hits, 0);
    /// ```
    #[must_use]
    pub fn snapshot(&self) -> PoolStatsSnapshot {
        PoolStatsSnapshot {
            hits: self.hits.load(Ordering::Relaxed),
            misses: self.misses.load(Ordering::Relaxed),
            checked_out: self.checked_out.load(Ordering::Relaxed),
            peak_checked_out: self.peak_checked_out.load(Ordering::Relaxed),
            bytes_checked_out: self.bytes_checked_out.load(Ordering::Relaxed),
            peak_bytes_checked_out: self.peak_bytes_checked_out.load(Ordering::Relaxed),
        }
    }
}

/// Immutable snapshot of pool statistics.
///
/// # Example
///
/// ```rust
/// use santh_bufpool::{BufferPool, PoolConfig, PoolStatsSnapshot};
///
/// let pool = BufferPool::new(PoolConfig::default());
/// let snap = pool.stats().snapshot();
/// assert_eq!(snap.checked_out, 0);
/// ```
#[derive(Debug, Clone, Copy)]
pub struct PoolStatsSnapshot {
    /// Number of pool hits (reuse).
    pub hits: usize,
    /// Number of pool misses (fallback alloc).
    pub misses: usize,
    /// Currently checked out.
    pub checked_out: usize,
    /// Peak simultaneous checkouts.
    pub peak_checked_out: usize,
    /// Total bytes currently checked out.
    pub bytes_checked_out: usize,
    /// Peak bytes checked out simultaneously.
    pub peak_bytes_checked_out: usize,
}