Struct Pool 

pub struct Pool(Arc<PoolInner>);

Available on Unix and crate feature pool only.

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.

Tuple Fields

0: Arc<PoolInner>

Implementations

impl Pool

pub fn new() -> Result<Pool>

Creates a pool over swap-backed extents, reserving one virtual region per size class. The pool starts with an unlimited budget, so nothing is evicted until Pool::set_budget tunes it.

pub fn with_backend(backend: ExtentBackend) -> Result<Pool>

As Pool::new, over backend. A file backend that cannot open returns the error, and the caller decides whether to fall back.

pub fn backend_kind(&self) -> BackendKind

The store the pool runs on.

fn with_backend_and_class_capacity( backend: ExtentBackend, class_capacity_bytes: usize, ) -> Result<Pool>

As Pool::with_backend, with a caller-chosen virtual reservation per size class.

pub fn insert_with( &self, len: usize, hints: ChunkHints, codec: &'static dyn ExtentCodec, fill: impl FnOnce(&mut [u64]), ) -> ChunkHandle

Allocates a chunk of len words and fills it in place: fill receives len words of unspecified contents and must overwrite all of them, so serialization writes its single copy straight into pool memory. The returned handle starts UnbackedResident, or Evicted when resident admission is full even after enforcement, in which case the payload is compressed to an extent on the calling thread before this returns. A zero len returns a length-0 handle holding no slot; payloads beyond the largest size class fall back to a plain heap allocation, always resident, a prototype limitation. hints steer eviction and write-behind policy; callers without placement knowledge pass the default. codec is the chunk’s ExtentCodec, fixed for its lifetime: the pool invokes it whenever the chunk moves across the extent boundary, and takes no interest in the stored form it produces.

Relies on abort-on-panic: a panic in fill that was caught would leak the slot and its resident-bytes accounting. All hosting binaries abort via mz_ore::panic::install_enhanced_handler, and pool consumers are dataflow operators, never code hosted under a catch_unwind boundary the way the optimizer is.

pub fn insert_typed( &self, body: Box<dyn TypedBody>, hints: ChunkHints, codec: &'static dyn ExtentCodec, ) -> ChunkHandle

Inserts a chunk in its owner’s in-memory form (see TypedBody), charged against the budget at its serialized length. Admission follows Pool::insert_with: a chunk the budget denies even after enforcement is serialized and compressed on the calling thread, and a body with no size class to evict into is serialized onto the heap.

fn insert_extent( &self, len: usize, class: Option<usize>, hints: ChunkHints, codec: &'static dyn ExtentCodec, fill: impl FnOnce(&mut [u64]), ) -> ChunkHandle

Inserts a chunk directly as a compressed extent, with no resident slot.

The fallback when the budget denies an insertion even after enforcement. The payload is filled into a temporary buffer and compressed on the calling thread, and the chunk starts evicted, so a denied insertion adds no resident bytes while the enforcer is busy. The temporary buffer, up to one size class, is heap memory outside the pool’s accounting. A chunk inserted here pays for compression even if it dies young, so under sustained pressure writes_elided undercounts the writes a resident insertion would have avoided.

pub fn stats(&self) -> PoolStats

Snapshot of the pool’s counters.

pub fn set_spill_threads(&self, threads: usize)

Enables or disables off-worker eviction I/O. The first call with threads > 0 spawns that many spill threads (spawn-once: later calls only toggle participation); threads == 0 falls back to inline eviction on the caller for subsequent victims, letting any queued work drain.

pub fn set_eager_backing(&self, eager: bool)

Enables or disables eager backing: when on, idle spill threads compress unbacked chunks to BackedResident ahead of pressure, so budget-driven eviction becomes a pure page release. Costs CPU on chunks that die before eviction would have reached them; pays at every pressure event. Only meaningful with spill threads spawned.

pub fn set_file_release(&self, interval: Duration, bytes_per_class: u64)

Retunes the file store’s warm-slot release: every interval, a spill thread punches up to bytes_per_class of each extent class’s free slots that still hold blocks, so the store’s disk usage follows its live extents. A zero interval or zero bytes disables the release. No effect on a swap-backed pool or one without spill threads.

The store’s capacity follows the volume’s free space independently of the release, re-derived by the spill threads every second. Without spill threads it changes only when the store hits ENOSPC.

pub fn set_budget(&self, budget_bytes: usize)

Retunes the resident-bytes budget in place and enforces it. Live handles share the new value immediately through their Arc<PoolInner>; a shrink takes effect by evicting on this call, a grow simply leaves more headroom for future inserts.

pub fn set_rss_target(&self, target_bytes: usize)

Retunes the ceiling on the pool’s total RSS — slots plus warm slots plus compressed-resident extents. The compressed tier’s capacity is the gap above the budget and warm cap; zero (the default) collapses the tier, paging extents out as soon as they are written. A shrink starts paging out the oldest extents on this call.

pub fn compressed_cap(&self) -> u64

The capacity of the compressed tier in bytes: the RSS target less the budget, the insert slack in use, and the warm-slot cap.

pub fn compressed_tier_above_cap(&self) -> bool

Whether the compressed tier is above Pool::compressed_cap, counted as the backend’s enforcement counts it. False once enforcement and the spill threads have caught up.

Trait Implementations

impl Clone for Pool

fn clone(&self) -> Pool

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Pool

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

Formats the value using the given formatter.