Skip to main content

DecoderPool

Struct DecoderPool 

Source
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

Source

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.

Source

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.

Source

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.

Trait Implementations§

Source§

impl Clone for DecoderPool

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for DecoderPool

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.