spiral/scandal/
read_cache.rs

1//! Explicit host-owned memory and I/O budgets for immutable payload reads.
2
3use serde::{Deserialize, Serialize};
4
5/// Encoded-page retention and speculative I/O limits. No disk cache is created.
6///
7/// Share one native cache across embedded scandal instances to bound their combined
8/// retained bytes. Decoded batches and buffers held by callers are outside this budget.
9#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
10#[serde(rename_all = "camelCase", deny_unknown_fields)]
11pub struct ReadCacheOptions {
12    /// Maximum retained encoded bytes; zero bypasses payload caching.
13    pub capacity_bytes: usize,
14    /// Page size; the last page is clipped to the immutable object's length.
15    pub page_bytes: usize,
16    /// Maximum physical reads in flight, including speculative reads.
17    pub max_in_flight: usize,
18    /// Adjacent pages eligible for opportunistic read-ahead; zero disables it.
19    pub read_ahead_pages: usize,
20    /// Maximum speculative reads in flight across this cache.
21    pub max_prefetch_in_flight: usize,
22}
23
24impl Default for ReadCacheOptions {
25    fn default() -> Self {
26        Self {
27            capacity_bytes: 128 * 1024 * 1024,
28            page_bytes: 256 * 1024,
29            max_in_flight: 16,
30            read_ahead_pages: 4,
31            max_prefetch_in_flight: 2,
32        }
33    }
34}
35
36/// Cumulative shared cache activity, including speculative and cancelled page loads.
37#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
38#[serde(rename_all = "camelCase")]
39pub struct ReadCacheStats {
40    /// Retained encoded bytes, excluding in-flight and caller-owned buffers.
41    pub cached_bytes: usize,
42    /// Reads satisfied by retained pages.
43    pub hits: u64,
44    /// Unique admitted page loads, including cancelled loads.
45    pub misses: u64,
46    /// Reads sharing another in-flight load.
47    pub coalesced: u64,
48    /// Physical page reads admitted by the I/O budget.
49    pub physical_reads: u64,
50    /// Requested page bytes, not exact completed network transfer.
51    pub physical_bytes: u64,
52}
spiral/scandal/read_cache.rs

spiral/scandal/
read_cache.rs
