pub struct DecoderPool { /* private fields */ }Expand description
Cloneable process-wide budget shared by multiple decoders.
The pool controls decode execution slots. It deliberately does not expose or promise a permanent one-to-one mapping between slots and operating-system threads. Each decoder retains its format-specific worker loop and scratch storage, while CPU-intensive tasks acquire a fair pool slot. A task releases its slot before any result or reader-channel operation that would block, so a slow consumer cannot occupy the shared decode budget.
The pool is opt-in and does not alter decoders built without
crate::DecoderBuilder::decoder_pool. Its workers value is an immutable
maximum; Self::set_worker_limit can change the live aggregate ceiling.
Decoders retain their own per-operation maximum and adaptive policy, so a
pool slot can remain unused when no attached input exposes useful work.
Under contention, stable max-min allowances prevent every decoder from spawning its complete configured headroom, while FIFO permit admission prevents one decoder from monopolizing execution. Cloning a pool shares the same state and does not create threads or reserve slots.
§Examples
use rapidgzip_core::{Decoder, DecoderPool};
use std::io;
let pool = DecoderPool::builder()
.workers(24)
.initial_worker_limit(8)
.build()?;
let decoder = Decoder::builder()
.decoder_threads(24) // Per-operation headroom.
.decoder_pool(pool.clone())
.build()?;
let mut first = decoder.open("sample-R1.fastq.gz")?;
let mut second = decoder.open("sample-R2.fastq.gz")?;
first.request_workers(12)?;
second.request_workers(12)?;
pool.set_worker_limit(16)?; // Aggregate execution ceiling.
// Applications normally consume independent readers concurrently.
io::copy(&mut first, &mut io::sink())?;
io::copy(&mut second, &mut io::sink())?;Implementations§
Source§impl DecoderPool
impl DecoderPool
Sourcepub fn stats(&self) -> DecoderPoolStats
pub fn stats(&self) -> DecoderPoolStats
Returns an approximate snapshot of aggregate pool activity.
The small member registry is locked briefly to sum per-decoder queue
depths and allowances. No decoder task or pool permit is held while
waiting for this snapshot. The returned value is Copy and does not
retain or control the pool.
Sourcepub fn set_worker_limit(
&self,
workers: usize,
) -> Result<(), DecoderPoolLimitError>
pub fn set_worker_limit( &self, workers: usize, ) -> Result<(), DecoderPoolLimitError>
Changes the maximum number of decode tasks that may execute at once.
The operation is nonblocking. Existing tasks retain their slots until they finish CPU-intensive work; no new task is admitted above the lower limit. Raising the limit redistributes worker allowances and wakes queued decoders immediately. The value is an aggregate ceiling, not a request that the pool keep that many tasks busy.
§Errors
Returns DecoderPoolLimitError for zero or a value above the pool’s
immutable configured maximum.
Sourcepub fn builder() -> DecoderPoolBuilder
pub fn builder() -> DecoderPoolBuilder
Creates a process-wide decoder pool.
Use DecoderPool::builder for named configuration. workers is the
immutable maximum number of simultaneously occupied decode execution
slots. initial_worker_limit optionally starts the mutable aggregate
ceiling below that maximum so an external scheduler can grow it later.
Neither value eagerly creates operating-system threads.
§Errors
Returns DecoderPoolConfigError when workers is zero or
initial_worker_limit is zero or greater than workers.