Struct Residency 

pub struct Residency<A, S>
where
    A: SlotArena,
    S: SwapStore,
{ /* private fields */ }

The generic paging core, lifted to atlas-tier (CUDA- and verbs-free). Re-exported under the atlas_tier names (no historical aliases). The page table: key → Loc over a bounded SlotArena (hot) backed by an unbounded SwapStore (cold), with LRU eviction of resident slots to disk.

Implementations

impl<A, S> Residency<A, S>

where A: SlotArena, S: SwapStore,

pub fn new(arena: A, swap: S) -> Result<Residency<A, S>, Error>

Unbounded disk tier (no cap). Prefer Residency::new_capped in production.

pub fn new_capped( arena: A, swap: S, max_disk_slots: usize, ) -> Result<Residency<A, S>, Error>

max_disk_slots bounds the on-disk record count (0 = unbounded). When full, spilling evicts the coldest on-disk snapshot (dropped → later GET misses → recompute), keeping the swap file at ≤ max_disk_slots records.

pub fn blob_bytes(&self) -> usize

pub fn stats(&self) -> &SwapStats

pub fn resident_count(&self) -> usize

pub fn total_keys(&self) -> usize

pub fn disk_count(&self) -> usize

Live on-disk records right now (≤ max_disk_slots when capped).

pub fn disk_high_water(&self) -> usize

Disk-record high-water mark — the honest swap-file size in records, which disk_count is not: crate::DirectSwapFile does not override SwapStore::discard_record (the default no-op), so a freed record’s blocks are never punched back out of the file. The file is bounded solely by index reuse through free_disk up to next_disk, so an operator sizing a partition must budget disk_high_water × blob_bytes. Reaches max_disk_slots + 1 under a cap: Residency::locate’s OnDisk arm pulls the faulting key out of disk_lru while its record is still live, so make_disk_room counts one fewer than exist.

pub fn max_disk_slots(&self) -> usize

The configured on-disk record cap (0 = unbounded).

pub fn arena(&self) -> &A

Direct arena access for the data plane. The peer writes the slots its clients one-sided-RDMA into/out of; in-process consumers should prefer Residency::put_blob / Residency::get_blob.

pub fn arena_mut(&mut self) -> &mut A

pub fn slot_offset(&self, slot: usize) -> u64

Byte offset of an arena slot (what the client RDMA-reads/writes).

pub fn alloc(&mut self, key: u64) -> Result<usize, Error>

PUT step 1 — reserve an arena slot for key. Evicts the coldest resident slot to disk if the arena is full (never rejects). The caller then RDMA-WRITEs the blob into slot_offset(slot) and calls commit(key). Re-PUT of a live key reuses its current slot (idempotent overwrite).

pub fn commit(&mut self, key: u64) -> Result<(), Error>

PUT step 2 — the client’s RDMA-WRITE into the reserved slot has landed; mark key resident (and hottest in the LRU).

pub fn locate(&mut self, key: u64) -> Result<Option<usize>, Error>

GET — ensure key is resident and return its arena slot (offset via slot_offset). Faults from disk into a slot if it was spilled (evicting a victim to make room). Ok(None) = unknown key (caller recomputes).

pub fn remove(&mut self, key: u64)

Drop key entirely, reclaiming its arena slot or disk record.

pub fn pin_read(&mut self, key: u64)

Read-pin key so its resident slot cannot be chosen as an eviction victim while a client’s one-sided RDMA READ of it is in flight (the GET→RDMA-read race: the peer replies with the offset and drops the lock before the client reads, so a concurrent allocation could otherwise spill+reuse the slot). Ref-counted for concurrent readers; the first pin removes the key from lru (like a Reserved slot). No-op unless the key is currently Resident.

pub fn unpin_read(&mut self, key: u64)

Release one read-pin taken by Residency::pin_read. When the last reader releases, the key rejoins lru as hottest (it was just read). No-op if the key holds no pin. Robust to the key having been removed while pinned: only re-adds to lru if still Resident and not already present.

pub fn read_pin_count(&self, key: u64) -> u32

Active read-pin count (test/introspection).

pub fn put_blob(&mut self, key: u64, bytes: &[u8]) -> Result<(), Error>

One-shot in-process PUT: reserve a slot, copy bytes into it, commit. Same NEVER-reject chain as the two-phase peer path (alloc → spill the coldest resident → drop the coldest on-disk key when capped). For consumers whose data plane is a memcpy rather than a client RDMA-WRITE.

pub fn get_blob(&mut self, key: u64, out: &mut [u8]) -> Result<bool, Error>

One-shot in-process GET: fault key in (if spilled) and copy its blob into out. Ok(false) = unknown key (caller recomputes).