metrale_storage/
kv_paging.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! 2026-09-25: KV blocks as a paging kind. `KvPagingBackend` keeps whole KV
4//! blocks in a peer's paging arena (handshake kind `PagingKind::KV`); the
5//! alternative is the one-sided `RdmaKvBackend`, whose client addresses a
6//! fixed arena at `base + group_id × group_stride`.
7//!
8//! Owner: metrale-storage KV tier.
9//! Invariants:
10//! - `connect_kv_peer_backend` returns `RdmaKvBackend` when `METRALE_KV_PAGING`
11//!   is unset or `0`, `KvPagingBackend` when it is `1`, and an error for any
12//!   other value (`ns::kv_paging_selected`).
13//! - A paging record is one KV block, `GroupLayout::block_bytes()`, keyed by
14//!   `ns::wire_key` of the block's K-head-0 group id.
15
16pub mod ns;
17
18#[cfg(all(feature = "cuda", metrale_rdma_verbs))]
19mod backend;
20#[cfg(all(feature = "cuda", metrale_rdma_verbs))]
21mod connect;
22
23#[cfg(all(feature = "cuda", metrale_rdma_verbs))]
24pub use backend::{KvPagingBackend, KvPagingConnect};
25#[cfg(all(feature = "cuda", metrale_rdma_verbs))]
26pub use connect::connect_kv_peer_backend;
27
28/// 2026-09-25: The error a KV paging GET miss becomes. The `StorageBackend`
29/// reads have no miss outcome, so a block the peer no longer holds fails the
30/// read.
31pub fn kv_miss_error(layer: u32, block: u32) -> anyhow::Error {
32    anyhow::anyhow!(
33        "kv-paging: block (layer {layer}, disk block {block}) is not on the peer — an \
34         evicted KV block is unrecoverable (silent KV loss would corrupt long-context \
35         output). Run the peer with --swap-cap-gb-kv 0 (unbounded KV disk) and size \
36         --max-blade-gb / METRALE_KV_PAGING_ARENA_GB for the working set"
37    )
38}
39
40#[cfg(test)]
41mod isolation_tests;
metrale_storage/kv_paging.rs

metrale_storage/
kv_paging.rs
