Struct Extent 

pub(crate) struct Extent {
    alloc_size: usize,
    comp_len: usize,
    resident: bool,
    incomplete_passes: u8,
    crc: u32,
    read_since_demotion: bool,
    home: Home,
}

Available on Unix and crate feature pool only.

One chunk’s compressed backing copy.

Fields

alloc_size: usize

Byte size of the backing allocation (the extent’s class size, or the heap layout on the fallback path): the granule the resident accounting and the pageout operate on.

comp_len: usize

resident: bool

Whether the extent’s pages are (engine-)resident: set at write and by Extent::read_into, cleared by a Extent::pageout whose residency observation found the whole range gone. Meaningful only in the Arena and Heap homes, see Extent::is_resident. Mutated only under the owning chunk’s state mutex.

incomplete_passes: u8

Consecutive pageout passes whose observation found pages still resident. Reset by Extent::read_into. At PAGEOUT_RETRY_CAP the extent stops being advised out.

crc: u32

Checksum of the first comp_len stored bytes, set when a demotion commits and verified by every file read.

read_since_demotion: bool

Whether the extent was read from its file since its demotion.

home: Home

Implementations

impl Extent

pub(crate) fn write( arena: &Arc<ExtentArena>, data: &[u64], codec: &dyn ExtentCodec, scratch: Scratch, ) -> Extent

Encodes data through codec into a fresh extent, preferring an arena slot and degrading to the heap when the payload’s class is exhausted. The pages stay resident; the pool’s RSS-target enforcement decides when Extent::pageout pushes them to the device.

Encoding goes through a reused thread-local scratch buffer so the extent slot can be chosen by the actual stored payload rather than the codec’s worst case. Worst-case sizing costs ~5.6× on compressible data, in swap capacity and in swap write bandwidth per eviction (the whole allocation is paged out), which at hydration eviction rates backs up device writeback and bloats the working set with swap-cache pages. scratch says whether the caller’s thread keeps the grown scratch for its next job.

fn ptr(&self) -> *mut u8

The in-memory copy of the stored bytes. Panics for a File extent, which has none.

pub(crate) fn alloc_size(&self) -> usize

The byte size of the extent’s allocation: the granule the resident accounting and the pageout operate on.

pub(crate) fn is_resident(&self) -> bool

Whether the extent’s pages are engine-resident (not pushed to the device since the last write or read). A Demoting extent is resident until its demotion commits, and a File extent never is.

pub(crate) fn is_reclaimable_arena(&self) -> bool

Whether the extent sits in an arena slot, resident and not retry-capped: the state RSS-target enforcement acts on, and the one in which freeing the extent avoids a device write.

pub(crate) fn is_demoting(&self) -> bool

Whether a demoter currently owns the extent.

pub(crate) fn file_bytes(&self) -> Option<usize>

The file slot’s size for a File extent, None otherwise.

pub(crate) fn file_location(&self) -> Option<FileLocation>

The file location of a File extent, None otherwise.

pub(crate) fn note_file_read(&mut self) -> bool

Records a read of the extent’s file, returning whether it was already read since its demotion.

pub(crate) fn begin_demotion(&mut self, file_slot: FileSlot) -> DemotionSource

Moves an Arena extent to Demoting toward file_slot and returns what the demoter’s unlocked write needs. Panics for any other home.

pub(crate) fn commit_demotion(&mut self, store: Arc<FileStore>, crc: u32)

Commits a demotion whose write succeeded: the extent moves to its File home with checksum crc, and its arena slot is freed with its pages discarded. Panics unless the extent is Demoting. The caller holds the chunk’s state lock, so no reader borrows the arena slot.

pub(crate) fn abort_demotion(&mut self) -> FileSlot

Returns a Demoting extent to its Arena home and hands back the file slot the demotion reserved, for the caller to return to the store. Panics unless the extent is Demoting.

pub(crate) fn pageout_capped(&self) -> bool

Whether the extent’s pageout retry budget is exhausted: consecutive incomplete passes reached PAGEOUT_RETRY_CAP, so callers stop calling Extent::pageout until a read resets the budget. Heap-fallback extents are permanently capped: they are never advised out and stay counted resident until freed.

pub(crate) fn pageout(&mut self) -> bool

Hints the kernel to push the extent’s pages to the swap device and observes the result: returns true, marking the extent non-resident, only when the observation finds the whole range unmapped (a page whose clean copy lingers in the swap cache counts as reclaimed). An incomplete pass leaves the extent fully resident for accounting and spends one unit of the retry budget: a single pinned page keeps the whole extent counted, which is the safe direction, and the retry budget exists exactly for such transient pins.

Callers must not invoke this on a Extent::pageout_capped extent.

pub(crate) fn comp_len(&self) -> usize

Compressed size in bytes, including the size prefix.

pub(crate) fn prefetch(&self)

Hints the kernel to swap the extent’s pages back in ahead of a read. A no-op for Demoting and File extents: the first is resident, and the second would need an asynchronous read into a buffer a later read can claim.

pub(crate) fn read_into(&mut self, codec: &dyn ExtentCodec, dst: &mut [u8])

Decodes the extent through codec into dst, which must be exactly the chunk’s body length. Reading an in-memory extent faults its pages back in, so it is resident again afterwards. The caller owns the accounting for that transition (the pool re-counts and re-enqueues it for the RSS target). A File extent is read per FileLocation::read_range_into and stays on file.

pub(crate) fn read_range_into( &mut self, codec: &dyn ExtentCodec, body_len: usize, offset: usize, dst: &mut [u8], )

Decodes the byte range [offset, offset + dst.len()) of the extent’s body_len-byte body into dst. The range must lie within the body, and body_len must be the body’s exact length (the codec validates it against the stored form). Residency effects are those of Extent::read_into regardless of the range: the stored form is one whole codec block, so any read faults (or reads from file) and decodes the entire extent, and a sub-range only narrows the final copy.

Trait Implementations

impl Debug for Extent

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

Formats the value using the given formatter.

impl Drop for Extent

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.

impl Send for Extent