pub struct Residency<A: SlotArena, S: SwapStore> { /* private fields */ }Expand description
Implementations§
Source§impl<A: SlotArena, S: SwapStore> Residency<A, S>
impl<A: SlotArena, S: SwapStore> Residency<A, S>
Sourcepub fn new(arena: A, swap: S) -> Result<Self>
pub fn new(arena: A, swap: S) -> Result<Self>
2026-09-25: Residency::new_capped with no disk cap.
Sourcepub fn new_capped(arena: A, swap: S, max_disk_slots: usize) -> Result<Self>
pub fn new_capped(arena: A, swap: S, max_disk_slots: usize) -> Result<Self>
2026-09-25: A residency over arena and swap with at most
max_disk_slots live on-disk records (0: no cap). The file can still
reach max_disk_slots + 1 records (see Residency::disk_high_water).
§Errors
slot_bytes() is 0, differs from swap.record_bytes(), or the arena has
no slot.
pub fn blob_bytes(&self) -> usize
pub fn stats(&self) -> &SwapStats
pub fn resident_count(&self) -> usize
pub fn total_keys(&self) -> usize
Sourcepub fn disk_count(&self) -> usize
pub fn disk_count(&self) -> usize
2026-09-25: Keys on disk now; at most max_disk_slots when capped.
Sourcepub fn disk_high_water(&self) -> usize
pub fn disk_high_water(&self) -> usize
2026-09-25: The highest record index ever allocated, plus one: the swap
file’s size in records. DirectSwapFile
keeps the default no-op discard_record, so its file never shrinks and
only index reuse through free_disk bounds it. Under a cap this reaches
max_disk_slots + 1: Residency::locate’s OnDisk arm takes the
faulting key out of disk_lru while its record is still live, so
make_disk_room counts one fewer record than exist.
Sourcepub fn max_disk_slots(&self) -> usize
pub fn max_disk_slots(&self) -> usize
2026-09-25: The on-disk record cap, 0 for none.
Sourcepub fn arena(&self) -> &A
pub fn arena(&self) -> &A
2026-09-25: The arena itself, for callers that move the bytes of a slot
they got from Residency::alloc or Residency::locate;
Residency::put_blob and Residency::get_blob do both steps.
pub fn arena_mut(&mut self) -> &mut A
Sourcepub fn slot_offset(&self, slot: usize) -> u64
pub fn slot_offset(&self, slot: usize) -> u64
2026-09-25: Byte offset of slot in the arena: slot * blob_bytes.
Sourcepub fn alloc(&mut self, key: u64) -> Result<usize>
pub fn alloc(&mut self, key: u64) -> Result<usize>
2026-09-25: Put, step 1: reserve an arena slot for key, spilling the
coldest unpinned resident to the store when no slot is free. The caller
writes the blob into the slot and then calls Residency::commit. A
resident or reserved key keeps its slot; an on-disk key gets a new slot
and its record is freed.
§Errors
Every slot is reserved or read-pinned, or the spill’s arena read or store write fails. On error the key keeps its previous location.
Sourcepub fn commit(&mut self, key: u64) -> Result<()>
pub fn commit(&mut self, key: u64) -> Result<()>
2026-09-25: Put, step 2: the blob is in the reserved slot; mark key
resident and, unless read-pinned, the hottest in lru. Committing a
resident key does nothing.
§Errors
key is neither reserved nor resident.
Sourcepub fn locate(&mut self, key: u64) -> Result<Option<usize>>
pub fn locate(&mut self, key: u64) -> Result<Option<usize>>
2026-09-25: Get: the arena slot holding key, faulting an on-disk key
back into a slot (which may spill another key). Ok(None) for an unknown
key. A reserved key returns its slot, whose bytes the caller has not
committed.
§Errors
No slot can be acquired, or the store read or arena write fails; the key then stays on disk and the acquired slot is freed.
Sourcepub fn remove(&mut self, key: u64)
pub fn remove(&mut self, key: u64)
2026-09-25: Forget key, freeing its arena slot or store record. A read
pin on it stays until unpin_read.
Sourcepub fn pin_read(&mut self, key: u64)
pub fn pin_read(&mut self, key: u64)
2026-09-25: Read-pin key so its slot is not an eviction victim while a
client reads it. Counted per reader; the first pin takes the key out of
lru. Does nothing unless key is resident.
Sourcepub fn unpin_read(&mut self, key: u64)
pub fn unpin_read(&mut self, key: u64)
2026-09-25: Release one pin taken by Residency::pin_read. After the
last one, a key that is still resident rejoins lru as the hottest. Does
nothing for a key with no pin.
Sourcepub fn read_pin_count(&self, key: u64) -> u32
pub fn read_pin_count(&self, key: u64) -> u32
2026-09-25: The number of read-pins on key.
Sourcepub fn put_blob(&mut self, key: u64, bytes: &[u8]) -> Result<()>
pub fn put_blob(&mut self, key: u64, bytes: &[u8]) -> Result<()>
2026-09-25: Put in one call: Residency::alloc, copy bytes into the
slot, Residency::commit.
§Errors
bytes is not blob_bytes long, alloc fails, or the arena write fails,
after which key is removed.