Struct Residency 

pub struct Residency<const ENTRIES: usize, const SLOTS: usize, const CATEGORIES: usize> { /* private fields */ }

Residency of streamed resources over page pools.

ENTRIES is how many resources it can track at once (resident, in flight, landed, backing off or pinned), SLOTS the most simultaneous allocations in any one pool, CATEGORIES the number of category numbers and pools. The whole state is plain integers sized by those three constants, so a static lives in .bss and nothing allocates.

See the crate docs for the frame loop. In short: each frame the engine calls Residency::step with what it wants; the step issues reads through the Host, evicts what must go and reports it; the transport reports outcomes with Residency::complete_read; the game installs landed payloads with Residency::begin_install and Residency::finish_install.

Implementations

impl<const ENTRIES: usize, const SLOTS: usize, const CATEGORIES: usize> Residency<ENTRIES, SLOTS, CATEGORIES>

pub const fn new(config: Config<CATEGORIES>) -> Self

An empty engine for config. const, so a static can hold it.

pub const fn config(&self) -> &Config<CATEGORIES>

The configuration.

pub const fn totals(&self) -> Totals

Counters since creation.

pub fn pool(&self, pool: usize) -> Option<&PagePool<SLOTS>>

Pool number pool, for fragmentation and occupancy reports.

pub fn category_pages(&self, category: Category) -> u32

Pages category currently holds.

pub fn category_entry_count(&self, category: Category) -> usize

Entries category currently holds pages for.

pub fn tracked_count(&self) -> usize

Resources currently tracked.

pub const fn in_flight_count(&self) -> usize

Requests in flight (including ones being cancelled).

pub const fn window(&self) -> u32

The scheduling window number: how many steps have run.

pub fn state(&self, key: ResourceKey) -> State

Lifecycle state of key (State::Absent when untracked).

pub fn is_resident(&self, key: ResourceKey) -> bool

Whether key is installed and usable.

pub fn handle(&self, key: ResourceKey) -> Option<Handle>

Handle of key’s allocation, in any state that holds pages.

pub fn resident_handle(&self, key: ResourceKey) -> Option<Handle>

Handle of key’s allocation when it is resident.

pub fn try_run(&self, handle: Handle) -> Option<PageRun>

Pages handle names, or None when it is stale. The one way to turn a handle into bytes (with crate::PageBuffer::bytes); call it on every use unless the entry is pinned.

pub fn payload_bytes(&self, key: ResourceKey) -> usize

Payload length in bytes of key (0 when untracked).

pub fn request_of(&self, key: ResourceKey) -> Option<RequestId>

The request in flight for key.

pub fn pin(&mut self, key: ResourceKey, class: Class) -> bool

Pin key: it cannot be evicted or moved while pinned, and the next steps request it at class if it is not resident. Pins nest (up to 255). false when the category is not configured, the table is full or the pin count is saturated.

pub fn unpin(&mut self, key: ResourceKey) -> bool

Drop one pin on key. false when it was not pinned.

pub fn pin_count(&self, key: ResourceKey) -> u8

Pins held on key.

pub fn touch(&mut self, key: ResourceKey)

Mark key as used now (refreshes its LRU age). Resident entries that the wanted list names are refreshed by Residency::step already.

pub fn complete_read( &mut self, request: RequestId, outcome: ReadOutcome, ) -> bool

The transport finished request. Returns false when the id is not an in-flight request (already reported, or never issued).

A Done that arrives after the engine asked to cancel is kept: the bytes are good, so the cancelled work is adopted.

pub fn begin_install(&mut self, key: ResourceKey) -> Option<Handle>

Start installing the landed payload of key: it is held in place and invisible until Residency::finish_install. Returns the allocation to install into, or None when key has not landed.

pub fn finish_install(&mut self, key: ResourceKey) -> bool

The install succeeded: key is resident.

pub fn abort_install(&mut self, key: ResourceKey) -> bool

Abandon the install without blame (for example the payload is no longer wanted): the pages are freed and the resource is simply absent.

pub fn fail_install(&mut self, key: ResourceKey) -> bool

The install failed (bad checksum, malformed payload): the pages are freed and the resource backs off before the next read.

pub fn next_install(&self, demand: Option<ResourceKey>) -> Option<ResourceKey>

The landed payload to install next: demand if it has landed, otherwise the most urgent landed payload the last step wanted.

pub fn evict_unlisted( &mut self, keep: &[ResourceKey], evictions: &mut [Eviction], ) -> usize

Evict every resident or landed, unpinned resource not in keep. Returns how many were evicted; stops early when evictions is full (call again). Reading and installing entries are never touched.

pub fn step<H: Host>( &mut self, wanted: &[Wanted], host: &mut H, evictions: &mut [Eviction], ) -> StepReport

Run one scheduling window.

wanted is everything the game wants resident now, in any order; the engine orders it by class, deadline and distance. Pinned resources are added at their pin class. Misses are issued to host nearest first; room is made by moving pages or by evicting; evictions are written to evictions and the step never evicts more than fits there. Apply them (unlink, drop cached views) before reading resident data again.

pub fn check_invariants(&self)

Check every cross-structure invariant (host tests and debug builds).