Struct ChunkHandle 

pub struct ChunkHandle { /* private fields */ }

Available on Unix and crate feature pool only.

Handle to one immutable chunk in a Pool. Dropping the handle frees the chunk: the slot (if resident) returns to the region free list with its physical pages released, and the extent (if any) is deallocated, discarding any swapped copy for free. Releasing the pages keeps RSS aligned with the resident_bytes gauge the budget enforcer trusts; without it, freed slots would hold warm pages the enforcer cannot see.

Implementations

impl ChunkHandle

pub fn read_into(&self, dst: &mut Vec<u64>)

Copies the whole contents into dst (cleared first), leaving the chunk’s residency untouched: a resident slot is copied out directly, and an evicted extent decompresses straight into dst without allocating a slot. A read therefore never raises resident bytes, never converts the chunk’s state, and hands out no reference into pool memory.

The copy runs under the chunk’s state lock, which is what makes the no-reference contract cheap: eviction takes the same lock, so there is no reader it could race. The admitting variant is ChunkHandle::read_into_admit.

pub fn read_range_into(&self, range: Range<usize>, dst: &mut Vec<u64>)

As ChunkHandle::read_into, restricted to the word range range of the chunk’s contents, which must lie within them. dst receives exactly the range.

The range narrows only the copy into dst: the swap backend’s stored form is a whole compressed block, so a cold read still faults and decompresses the entire extent, and accounting is that of a whole-chunk read. A backend with a rangeable stored form can serve the same call with range-proportional I/O.

pub fn read_into_admit(&self, dst: &mut Vec<u64>)

As ChunkHandle::read_into, except that an evicted chunk is re-admitted to BackedResident (its extent kept, its touched bit set) when a slot is available from free budget headroom or by stealing from a clean backed victim of the same size class, never by evicting or compressing anything. When neither source yields a slot the read is served as a plain decompress and the chunk stays evicted.

For demand reads on probe paths, where the same chunk is likely to be read again. Merge, drain, and other consume-once paths should use ChunkHandle::read_into or ChunkHandle::take: admitting there churns the clean-victim stock that eager backing exists to build, evicting probe targets to house data about to die.

pub fn read_range_into_admit(&self, range: Range<usize>, dst: &mut Vec<u64>)

As ChunkHandle::read_into_admit, restricted to the word range range per ChunkHandle::read_range_into. Admission is whole-chunk regardless of the range: the acquired slot holds the entire body.

pub fn take(self, dst: &mut Vec<u64>)

Copies the whole contents into dst (per ChunkHandle::read_into, never admitting) and frees the chunk, cancelling any in-flight backing write.

pub fn prefetch(&self)

Advisory a consumer may issue before a bulk read: hints the kernel to swap an evicted chunk’s extent back in, and is a no-op in every other state. Never blocks on I/O (MADV_WILLNEED is asynchronous).

pub fn prefetch_range(&self, range: Range<usize>)

As ChunkHandle::prefetch, scoped to the word range range of the chunk’s contents. The range is advisory: a backend hints at whatever granularity its stored form permits, and the swap backend’s stored form is a whole compressed block, so it hints the entire extent.

Trait Implementations

impl Debug for ChunkHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for ChunkHandle

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.