Module snapshot_swap 

2026-09-25: Paging core of the SSM snapshot tier: the peer’s TCP control protocol and paging loops, the client side of that protocol (wire), and MmapSlotArena (mmap_arena). Re-exports the generic tier types it builds on.

Owner: storage, SSM snapshot tier. Invariants: none beyond the types.

The peer runs a Residency over its RDMA-registered arena and an NVMe swap file, and owns residency, so every client of one arena shares its cache. The paging loops register no memory: blobs move between arena and swap under the rkeys each connection registered in its handshake.

Re-exports

pub use crate::tier::DirectSwapFile;

pub use crate::tier::MemSwapStore;

pub use crate::tier::Residency;

pub use crate::tier::SlotArena;

pub use crate::tier::SwapStats;

pub use crate::tier::SwapStore;

pub use crate::tier::VecSlotArena;

Structs

MmapSlotArena

2026-09-25: SlotArena over the peer’s mapped arena, from a raw base pointer. The peer copies between slots and its swap file; clients RDMA into and out of the same slots. The arena registers nothing; the peer registers the mapping per connection.

PagingKind

2026-09-25: The tier a paging arena serves. Only SSM and KV are accepted (parse_paging_header); the read-only expert and weight peers use their own handshake.

Enums

PagingReply

2026-09-25: Result of one control request, ready to serialise.

Constants

OP_ALLOC

OP_BYE

OP_COMMIT

OP_GET

OP_REMOVE

PAGING_MAGIC_V2

2026-09-25: The only accepted first u64 on the paging port, ASCII “PAGE” + 2. The [u8 kind] that follows lets one peer keep an arena per (kind, blob_bytes).

ST_ERR

ST_MISS

ST_OK

Functions

client_alloc

2026-09-25: Reserve a slot for key and return its arena offset; a non-OK status is an error.

client_bye

2026-09-25: Tell the peer to end the paging loop; no reply is read.

client_commit

2026-09-25: After the WRITE has completed, mark key resident.

client_get

2026-09-25: Some(offset) to READ from, or None when the peer has no such key.

client_remove

2026-09-25: Ask the peer to drop key.

dispatch

2026-09-25: Execute one control op against res and return the reply; no I/O, so the protocol is testable without a socket or RDMA.

encode_paging_v2_header

2026-09-25: The 25-byte header every client sends first, in paging and raw mode: [u64 PAGING_MAGIC_V2 LE][u8 kind][u64 arena_bytes LE][u64 blob_bytes LE]. The RailSet exchange follows it.

parse_paging_header

2026-09-25: Parse the rest of the handshake header, given the first u64 the caller has read: [u8 kind][u64 arena_bytes][u64 blob_bytes]. A first u64 other than PAGING_MAGIC_V2 (with its own message for the “PAGE” + 1 value), or a kind other than SSM/KV, is an error.

run_paging_loop

2026-09-25: The peer’s control loop over one residency: read [op][u64 key], dispatch, reply, until BYE or a failed read of the op byte.

run_paging_loop_shared

2026-09-25: run_paging_loop over a residency shared by many connections, so a blob one client PUTs another can GET under the same key. The lock is held for each dispatch, which may move bytes to or from swap, and never across a TCP read or write.

staging_chunk_bytes

2026-09-25: Chunk size of the striped snapshot transfer: METRALE_SSM_CHUNK_BYTES, or 1 MiB when it is unset, unparsable or below 4096.

staging_depth

2026-09-25: Chunks in flight per rail: METRALE_SSM_PIPELINE_DEPTH, or 16 when it is unset or unparsable, clamped to 1..=128.

stripe_plan

2026-09-25: Split a blob_bytes transfer into chunk_bytes chunks dealt round-robin to n_rails, as per-rail lists of (offset, len). The offset is the chunk’s position in both the staging buffer and the peer slot, so one copy assembles the blob whichever rail moved each chunk. Only the last chunk may be short. Zero chunk_bytes or n_rails counts as 1.