Struct BufferPoolConfig 

pub struct BufferPoolConfig { /* private fields */ }

Configuration for a buffer pool.

The class layout is a set of power-of-two size classes, each with its own tracked-buffer limit. Enabled classes do not need to be contiguous, and requests route to the smallest enabled class that fits.

Shape builders do not commute. Each builder applies to the layout produced by the previous one: replacement builders (Self::with_size_class_range, Self::with_size_classes) discard the current layout, uniform builders (Self::with_max_per_class, Self::with_bytes_per_class) overwrite every enabled limit, and Self::with_budget_bytes snapshots and rescales the shape that exists at that call.

Implementations

impl BufferPoolConfig

pub fn for_network() -> Self

Network I/O preset: 1KB to 128KB buffers, 4096 per class, not prefilled.

Network operations typically need multiple concurrent buffers per connection (message, encoding, encryption) so we allow 4096 buffers per size class.

pub fn for_storage() -> Self

Storage I/O preset: page_size (usually 4KB) to 8MB buffers, 64 per class, not prefilled.

pub const fn with_pool_min_size(self, pool_min_size: usize) -> Self

Returns a copy of this config with a new minimum request size that uses pooling.

pub fn with_size_class_range( self, min: NonZeroUsize, max: NonZeroUsize, max_buffers: NonZeroU32, ) -> Self

Returns a copy of this config whose layout is the inclusive, contiguous power-of-two range from min to max with a uniform limit.

This replaces the complete class layout.

Panics

• min or max is not a power of two
• min or max exceeds isize::MAX
• max < min

pub fn with_size_classes<I, C>(self, classes: I) -> Self

where I: IntoIterator<Item = C>, C: Into<BufferPoolClassConfig>,

Returns a copy of this config whose layout is exactly the given classes.

This replaces the complete class layout. Input order does not matter, classes are normalized into ascending size order.

Panics

• classes is empty
• a class size is not a power of two
• a class size exceeds isize::MAX
• two classes have the same size

pub fn with_size_class( self, size: NonZeroUsize, max_buffers: NonZeroU32, ) -> Self

Returns a copy of this config with the given class enabled, replacing its limit if it is already enabled.

Panics

• size is not a power of two
• size exceeds isize::MAX

pub fn without_size_class(self, size: NonZeroUsize) -> Self

Returns a copy of this config with the given class removed.

Requests that previously routed to the removed class route to the next larger enabled class.

Panics

• size is not a power of two
• size exceeds isize::MAX
• no class with size is enabled
• the class is the final enabled class

pub fn with_max_per_class(self, max_buffers: NonZeroU32) -> Self

Returns a copy of this config with the same limit on every enabled class.

pub fn with_bytes_per_class(self, bytes: NonZeroUsize) -> Self

Returns a copy of this config where every enabled class has approximately the same tracked-byte weight.

Each enabled class’s limit becomes max(1, bytes / size), so limits halve as class sizes double. This is a one-shot count transformation, not a stored byte policy, and it never disables a class.

Panics

Panics if a derived limit exceeds u32::MAX.

pub const fn with_parallelism(self, parallelism: NonZeroUsize) -> Self

Returns a copy of this config with a new expected parallelism.

The global freelist derives its stripe count from this target and the class capacity. This value also controls thread-cache capacity when the thread-cache policy is automatic. The automatic policy reserves about half of each class for the global freelist and divides the remaining capacity across expected threads.

pub const fn with_max_thread_cache_capacity( self, capacity: NonZeroUsize, ) -> Self

Returns a copy of this config with an explicit per-thread cache size.

Each size class keeps a small per-thread cache of free buffers for same-thread reuse. By default its capacity is derived per class from the class limit and Self::parallelism, reserving about half of the class for the shared global freelist. An explicit capacity replaces that derivation and may be larger or smaller than the derived value.

The effective capacity for each class is min(capacity, class limit). Clamping happens independently per class, so one small class cannot invalidate the configuration.

Buffers held in a thread’s cache are invisible to other threads until they spill to the global freelist or the thread exits, and each thread can retain up to the effective capacity of every class it touches. Larger values favor same-thread reuse while smaller values favor cross-thread visibility and a lower per-thread memory ceiling.

Global-freelist striping is set separately by Self::with_parallelism.

pub const fn with_thread_cache_disabled(self) -> Self

Returns a copy of this config with thread-local caching disabled.

Global-freelist striping is set separately by Self::with_parallelism.

pub const fn with_prefill(self, prefill: bool) -> Self

Returns a copy of this config with a new prefill setting.

pub const fn with_alignment(self, alignment: NonZeroUsize) -> Self

Returns a copy of this config with a new alignment.

pub fn with_budget_bytes(self, budget: NonZeroUsize) -> Self

Returns a copy of this config with all class limits proportionally rescaled under a strict tracked-byte ceiling.

This snapshots the currently enabled classes and their limits, then chooses the greatest common proportional scale for which the total tracked capacity sum(size * scaled_limit) stays within budget, where scaled_limit = max(1, floor(limit * scale)). Scaling may raise or lower limits, never disables a class, and may deliberately leave part of the budget unused rather than distort the requested shape.

The budget covers tracked buffer payload capacity only. It does not include allocator metadata, alignment overhead, or pool bookkeeping.

This is a one-shot transformation, not a stored policy. Later builder calls may change the resulting total, and calling this again rescales the already scaled limits rather than the shape they were derived from.

Panics

• budget is smaller than one buffer from every enabled class
• the budget would require scaling a limit above u32::MAX

pub fn size_classes( &self, ) -> impl ExactSizeIterator<Item = BufferPoolClassConfig> + '_

Returns an iterator over enabled classes in ascending size order.

pub fn class_for(&self, size: usize) -> Option<BufferPoolClassConfig>

Returns the enabled class that serves a pooled request of size bytes, or None if size exceeds the largest enabled class.

Requests route to the smallest enabled class that fits, so in sparse layouts the returned class may be much larger than the request. This reports class shape only: zero-sized requests and requests below Self::pool_min_size bypass the pool, and oversized requests fall back to untracked aligned allocations with capacity at least as large as the request.

pub const fn pool_min_size(&self) -> usize

Returns the minimum request size that uses pooled allocation.

pub const fn prefill(&self) -> bool

Returns whether every tracked buffer is created during pool construction.

pub const fn alignment(&self) -> NonZeroUsize

Returns the buffer alignment.

pub const fn parallelism(&self) -> NonZeroUsize

Returns the expected number of threads concurrently accessing the pool.

pub fn min_size(&self) -> NonZeroUsize

Returns the smallest enabled class size.

pub fn max_size(&self) -> NonZeroUsize

Returns the largest enabled class size.

pub fn max_tracked_bytes(&self) -> usize

Returns sum(class size * class limit), saturating at usize::MAX.

A saturated result means the configured maximum tracked capacity is at least that large.

Trait Implementations

impl Clone for BufferPoolConfig

fn clone(&self) -> BufferPoolConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BufferPoolConfig

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

Formats the value using the given formatter.