Crate rylv_pool 

rylv-pool

Generic pooling with pluggable providers, extracted from rylv_utils.

• PoolItem defines how reusable values are reset.
• PoolProvider controls acquisition, returns, and prewarming.
• PoolProvider::Entry lets each provider choose its own ownership handle and routing context, with mutable access and StableDeref guarantees.
• PoolGuard returns values automatically on drop and implements StableDeref.
• FixedThreadLocalPool<T, N> provides fixed-capacity thread-local storage and lock-free returns from other threads. N limits retained entries, not active guards. Its static TLS key reference implements PoolProvider directly.
• PoolError preserves factory errors and captured unwind panic payloads.

Public types are imported from the crate root. FixedThreadLocalEntry is an opaque associated type of the thread-local provider; its routing details remain private. Storage internals and test inspection helpers are not part of the API.

The crate depends only on stable_deref_trait.

use rylv_pool::{FixedThreadLocalPool, FixedThreadLocalPoolGuard, PoolItem};

#[derive(Default)]
struct Scratch(Vec<u8>);

impl PoolItem for Scratch {
    fn reset(&mut self) {
        self.0.clear();
    }
}

thread_local! {
    static POOL: FixedThreadLocalPool<Scratch, 8> = FixedThreadLocalPool::new();
}

let mut scratch = FixedThreadLocalPoolGuard::acquire(&POOL)?;
scratch.0.extend_from_slice(b"reusable storage");

Testing and CI

CI includes stable and MSRV builds on Linux/macOS/Windows, debug/release tests, Clippy, formatting, documentation, coverage artifacts, Miri, fuzzing, dependency security and license checks, semver checks, and tag-driven releases.

The coverage gate requires at least 95% of production lines. See CI setup for commands, artifacts, and required GitHub configuration, and test coverage map for the scenarios.

make verify runs the normal local checks. make coverage, make miri, and make fuzz opt into the additional tools. cargo test --locked runs the root crate’s unit, integration, and documentation tests.

Benchmarks

make bench runs Criterion benchmarks in the optimized bench profile. Criterion is a development dependency. They cover local reuse, misses, prewarming, remote returns, and draining, with small values and reusable buffers. For example:

make bench BENCH_ARGS='warm/ --sample-size 50 --measurement-time 3'
make bench BENCH_ARGS='--list'

See benchmark methodology for the scenarios, timing units, and comparison limits. Normal tests run the scenarios as smoke checks without reporting timings. Pull-request CI compares baselines with critcmp and fails on mean slowdowns greater than 15%; the threshold is configurable.

License

Licensed under either Apache License 2.0 or MIT license, at your option.

Structs

FixedThreadLocalPool

Per-thread pool with capacity N fixed at compile time.

PanicError

The original payload of a captured unwind panic.

PoolGuard

Exclusive, address-stable guard returned by a PoolProvider.

Enums

PoolError

A factory failure or an unwinding panic during a pool operation.

Traits

PoolItem

A reusable value managed by a pool.

PoolProvider

Supplies complete take, return, and warming operations for a pool.

Type Aliases

FixedThreadLocalPoolGuard

Guard using a consumer-defined thread-local pool key as its provider.