Module pool_config 

Process-wide installation and configuration point for the buffer pool that backs chunk spilling.

Chunk spill consumers, arriving with the chunk-batcher work, resolve their backing through active_pool at each spill decision, so live reconfiguration takes effect on the next call. The pool itself (mz_ore::pool::Pool) is a process singleton: live chunk handles keep their Arc into it, so replacing it on reconfigure would split residency accounting across two budgets. Operator-driven tunes instead retune the one instance in place via apply_pool_config.

See doc/developer/design/20260610_buffer_managed_state.md for the buffer-pool design.

Modules

metrics

Prometheus metrics for the process-wide buffer pool and columnar chunk work.

Structs

PoolPagerConfig

Inputs to apply_pool_config. All sizes are absolute bytes; fractions are resolved by the caller against physical RAM (see mz_ore::memory::physical_memory_bytes), never against an announced limit that may include swap.

Enums

ExtentBackend

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

Statics

FILE_FALLBACK 🔒

Whether the pool was asked for a file backend and installed on swap.

GLOBAL_POOL 🔒

Process-wide buffer pool shared by every spill consumer in the process.

POOL_MODE 🔒

Whether apply_pool_config has installed the pool as the process’s spill mechanism. active_pool reads this so consumers stay inert until the first config apply budgets the pool.

Functions

active_pool

Returns the pool only when apply_pool_config has installed and budgeted it, and never initializes anything itself. Chunk spill consumers resolve their backing through this at each spill decision, so an unconfigured or gated-off process keeps every chunk resident.

apply_pool_config

Applies a buffer-pool configuration, installing the pool as the process’s spill mechanism. This is the only path that constructs the pool. A process that never calls it, because the spill gate is off or it is unconfigured, never reserves the pool’s address space or spawns its spill threads. Returns false (and changes nothing) if the pool is unavailable because its virtual reservation failed.

apply_to 🔒

apply_pool_config over an explicit slot, so tests can observe the install-once behavior without racing on the process-wide pool.

build_pool 🔒

Builds the pool for backend, creating a file backend’s directory. A file store that cannot be created or opened falls back to swap, which needs no scratch space. This is the only place that decides the fallback.

file_backend_fell_back

Whether apply_pool_config was asked for a file backend and installed the pool on swap instead. Covers installation only: a store that later disables writes on an I/O error reports through mz_column_pool_extent_file_write_errors_total.

global_pool_peek

Returns the process-wide buffer pool only if something already initialized it; never triggers the virtual reservation itself. Metrics scrapes read through this so that observing a process (which may never install the pool) does not mmap the pool’s address space as a side effect.

spill_threads_for_workers

Spill threads for a process with workers timely workers at fraction.