Module pool 

Available on Unix and crate feature pool only.

Prototype buffer pool for dataflow state. See doc/developer/design/20260610_buffer_managed_state.md.

The pool is the cache: size-class anonymous virtual-memory regions whose slots hold resident chunks. Slots are scoped to residency — eviction returns a chunk’s slot to the free list along with its physical pages — so slot demand tracks the resident set (bounded by the budget), not the potentially unbounded live backlog. Reads are copy-out (ChunkHandle::read_into): a resident slot is copied and an evicted extent decompressed straight into the caller’s buffer, all under the chunk’s state lock, so no reference into pool memory escapes the pool and a read leaves residency untouched. The backing is the extent store of the design’s Layer 1: a slot in a pool-owned anonymous-memory extent arena holding the chunk’s lz4-compressed bytes, later paged to swap or demoted to file per the pool’s ExtentBackend.

Memory descends a ladder of tiers, each with its own ceiling and each cheaper to vacate than the one above:

• Slots (uncompressed, free reads) — bounded by the budget; crossing it compresses the oldest chunks into extents and releases their slots.
• Warm free slots (pages kept for fault-free reuse) — bounded by the warm cap.
• Compressed-resident extents (reads decompress, no device) — bounded by the headroom the RSS target leaves above the first two; crossing it pushes the oldest extents to the swap device with MADV_PAGEOUT.
• The swap device (overflow). Reads fault and decompress. A pool built over ExtentBackend::File demotes extents to files in a scratch directory instead, and reads them back with pread.

Residency is a state, not a type. It descends through eviction and ascends through exactly one transition: an admitting read (ChunkHandle::read_into_admit) lifts an evicted chunk back to BackedResident when a slot is free within the budget or stealable from a clean backed victim of the same class, never by evicting or compressing anything. Plain reads (ChunkHandle::read_into) leave residency untouched. Eviction I/O runs on spill threads when enabled — WriteInFlight marks a chunk whose compression a spill thread owns — and inline on the evicting caller otherwise. Chunks are immutable after Pool::insert_with, which is what makes a BackedResident slot always identical to its extent and its eviction free of I/O.

Freeing an UnbackedResident chunk is a pure memory operation — the design’s “never write dead data” win, surfaced as writes_elided in PoolStats. Budget pressure evicts cold chunks via second-chance FIFOs banded by the caller-supplied generational depth (ChunkHints).

Modules

extent 🔒

The extent type and the arena that holds extents in memory, the first home of every extent whatever the pool’s backend.

file 🔒

The file-backed extent store: a userspace extent allocator over one anonymous file per extent class in a scratch directory.

region 🔒

Size-class virtual-memory regions for the buffer pool.

Structs

ChunkHandle

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.

ChunkHints

Advisory placement hints for a chunk, supplied at insert and immutable thereafter (merges mint new chunks, so a chunk’s generation never changes). Hints steer policy — eviction order and write-behind candidacy — never correctness: a mislabeled chunk performs worse, while the budget and residency invariants hold regardless.

ChunkMeta 🔒

ChunkState 🔒

Counters 🔒

ExtentEntry 🔒

An extent_queue entry.

FileRelease 🔒

The schedule of the file store’s warm-slot release.

IdentityCodec

The identity ExtentCodec: the stored form is the body. Encode and decode are copies, and range reads copy the range directly, so a chunk stored under this codec pays no compression work in either direction while remaining fully budgeted and backed like any other extent.

ParkedExtents 🔒

extent_queue entries set aside per extent class. See PoolInner::parked_extents.

Pool

A buffer pool over compressed extents, backed by swap or by files per its ExtentBackend. Cheap to clone. All clones share one budget and one backing store.

PoolInner 🔒

The shared state behind every Pool handle. One per process in practice; Pool clones and chunk handles share it through an Arc, so it lives until the last handle and spill thread release it.

PoolStats

Snapshot of pool counters.

Spill 🔒

Hand-off point between budget enforcement and spill threads. Eviction I/O (compression and the synchronous-reclaim pageout) runs on spill threads when enabled, keeping multi-millisecond work off the threads that trip the budget; with no spill threads, eviction runs inline on the caller.

Enums

BackendKind

The store a pool actually runs on.

Demotion 🔒

The outcome of one PoolInner::demote, as it bears on the pass.

ExtentBackend

The extent store a pool is built over, fixed for the pool’s lifetime.

ExtentStore 🔒

The extent store behind a PoolInner.

Pass 🔒

Which kind of caller runs a PoolInner::enforce_compressed_cap pass.

Residency 🔒

Residency state of a chunk.

SpillKind 🔒

What a spill thread does with a chunk once compressed.

Constants

CLASS_CAPACITY_BYTES 🔒

Virtual reservation per size class. Purely virtual: physical memory materializes only for slots in use, and slots are scoped to residency, so this must exceed the largest plausible resident set per class, the budget plus in-flight slack, not the backlog. It is deliberately enormous (address space costs nothing, and touched pages are bounded by peak residency) so that no realistic budget, on any machine size, reaches the heap-fallback path.

DEMOTION_PASS_BYTES 🔒

The most extent bytes one file-mode pass demotes: a spill thread’s pass while the eviction queue is empty, and an inline pass while spill threads exist. With queued evictions a spill thread’s pass demotes one extent, so the thread alternates one eviction with one demotion.

DEPTH_BANDS 🔒

Number of depth bands the eviction queues are split into; depths at or beyond the last band share it.

FILE_CAPACITY_REFRESH_INTERVAL 🔒

How often a spill thread re-derives the file store’s capacity from the volume’s free space.

READ_LATENCY_BUCKETS

Number of read-latency buckets. Bucket i < READ_LATENCY_BUCKETS - 1 counts reads that took less than 32 µs << i and, for i > 0, at least 16 µs << i. The last bucket counts reads of 65.536 ms and more.

SPILL_IN_FLIGHT_MAX

Beyond this many queued or in-flight spill entries, eviction degrades to inline on the caller: bounded memory overshoot under burst beats an unbounded queue of still-resident chunks.

SPILL_PARK_TIMEOUT 🔒

How long an idle spill thread parks, and how often a spill thread retries demotion while the file store’s full hint is set.

WORD_BYTES 🔒

Bytes per word of a chunk body. Chunk lengths are in u64 words.

Statics

IDENTITY_CODEC

The IdentityCodec instance to pass to Pool::insert_with.

Traits

ExtentCodec

A chunk-provided transform between a chunk’s body bytes and the stored bytes its extent holds. The pool owns scheduling: spill threads, the residency state machine, cancellation, and the ledger. It invokes the codec on opaque bytes at the extent boundary, encode when backing a chunk (on a spill thread, or inline under overload) and decode when reading an evicted one, possibly under the chunk’s state lock. The pool itself has no opinion on the stored form: framing, compression, and validation all belong to the codec.

TypedBody

A chunk body the pool holds in its owner’s in-memory form, serializing it only when it has to leave that form: on eviction, on backing, and on a copy-out read. Under budget a typed chunk therefore costs the pool its bookkeeping and nothing else, and ChunkHandle::take_typed hands the body back without a copy.

Functions

backstop_threshold 🔒

The tier size at which callers with spill threads present enforce the compressed cap inline, and where an inline file-mode pass stops.

band 🔒

The eviction-queue band for a chunk of depth.

class_bit 🔒

The bit of class in a pass’s refused-class mask, or 0 for a class the mask cannot represent, which the pass then probes on every visit.

insert_slack 🔒

Resident bytes insertions may reserve above budget while enforcement catches up. Slots can transiently hold this much past the budget, so the RSS target reserves it too.

max_stored_len

The largest stored form ExtentCodec::encode may produce for a body_len-byte body: an incompressible-input expansion matching lz4’s worst case plus a four-byte length prefix. The extent store’s size-class ladder is provisioned to this bound, so a codec that exceeds it can strand payloads with no class to hold them (they degrade to unpageable heap fallbacks).

serialize_typed 🔒

The serialized form of a typed body, in a fresh buffer.