spiral-sdk 0.1.10

//! Explicit host-owned memory and I/O budgets for immutable payload reads.

use serde::{Deserialize, Serialize};

/// Encoded-page retention and speculative I/O limits. No disk cache is created.
///
/// Share one native cache across embedded scandal instances to bound their combined
/// retained bytes. Decoded batches and buffers held by callers are outside this budget.
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ReadCacheOptions {
    /// Maximum retained encoded bytes; zero bypasses payload caching.
    pub capacity_bytes: usize,
    /// Page size; the last page is clipped to the immutable object's length.
    pub page_bytes: usize,
    /// Maximum physical reads in flight, including speculative reads.
    pub max_in_flight: usize,
    /// Adjacent pages eligible for opportunistic read-ahead; zero disables it.
    pub read_ahead_pages: usize,
    /// Maximum speculative reads in flight across this cache.
    pub max_prefetch_in_flight: usize,
}

impl Default for ReadCacheOptions {
    fn default() -> Self {
        Self {
            capacity_bytes: 128 * 1024 * 1024,
            page_bytes: 256 * 1024,
            max_in_flight: 16,
            read_ahead_pages: 4,
            max_prefetch_in_flight: 2,
        }
    }
}

/// Cumulative shared cache activity, including speculative and cancelled page loads.
#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ReadCacheStats {
    /// Retained encoded bytes, excluding in-flight and caller-owned buffers.
    pub cached_bytes: usize,
    /// Reads satisfied by retained pages.
    pub hits: u64,
    /// Unique admitted page loads, including cancelled loads.
    pub misses: u64,
    /// Reads sharing another in-flight load.
    pub coalesced: u64,
    /// Physical page reads admitted by the I/O budget.
    pub physical_reads: u64,
    /// Requested page bytes, not exact completed network transfer.
    pub physical_bytes: u64,
}