Struct ScratchBank 

pub struct ScratchBank<T, const N: usize>
where
    T: ScratchElement,
{ /* private fields */ }

A fixed set of same-typed scratch pools for domain-specific temporary roles.

Transform crates commonly need several independent thread-local scratch buffers for one element type: e.g. Stockham data, PFA data, Rader padding, and Bluestein chirps. ScratchBank<T, N> keeps those roles in one const-generic provider-owned container while preserving the same zero-copy ScratchPool::with_scratch access contract for each slot.

Implementations

impl<T, const N: usize> ScratchBank<T, N>

where T: ScratchElement,

pub const fn new() -> ScratchBank<T, N>

Creates a bank of empty scratch pools.

Examples found in repository

examples/book_scratch_pool.rs (line 68)

fn main() {
    // Construct a pool locally and use it directly (not thread_local! here
    // to avoid the clippy::missing_const_for_thread_local false positive on
    // 1.97.0 — see ATLAS-MNEMOSYNE-CI-1).  In production callers store the
    // pool in thread_local! storage so it persists between calls.
    let f64_pool: ScratchPool<f64> = ScratchPool::new();
    let f32_pool: ScratchPool<f32> = ScratchPool::new();

    // Simple single-level scratch use: compute a dot product via a temp buffer.
    f64_pool.with_scratch(1024, |scratch| {
        for (i, slot) in scratch.iter_mut().enumerate() {
            *slot = i as f64;
        }
        let partial: f64 = scratch.iter().sum();
        println!(
            "sum of 0..1024 via scratch: {} (expected {})",
            partial,
            (0..1024usize).sum::<usize>() as f64,
        );
        assert_eq!(partial, (0..1024usize).sum::<usize>() as f64);
    });

    // Nested borrows: outer scratch holds the signal; inner holds a window.
    f64_pool.with_scratch(256, |signal| {
        for (i, s) in signal.iter_mut().enumerate() {
            *s = (i as f64).sin();
        }
        f64_pool.with_scratch(16, |window| {
            window.copy_from_slice(&signal[..16]);
            let dp = dot_product(window, &signal[..16]);
            println!("windowed dot-product: {dp:.6}");
            assert!(dp.is_finite());
        });
    });

    // F32 pool: same API, different element type.
    f32_pool.with_scratch(64, |buf| {
        buf.fill(1.0_f32);
        let total: f32 = buf.iter().sum();
        println!("f32 scratch sum: {total}");
        assert_eq!(total, 64.0_f32);
    });

    // Banked scratch keeps multiple related roles in one const-generic group,
    // which matches transform pipelines that need independent temporary views
    // without falling back to the system allocator.
    let bank: ScratchBank<f64, 2> = ScratchBank::new();
    bank.with_scratch::<1, _>(32, |scratch| {
        scratch.fill(3.5);
        assert!(scratch.iter().all(|v| *v == 3.5));
    });

    // Bounded provisioning retains the working set while making geometric
    // growth headroom reclaimable at a consumer-selected quiescent point.
    let bounded_pool: ScratchPool<u32> = ScratchPool::new();
    bounded_pool.with_scratch_bounded(1024, |_| {});
    bounded_pool.with_scratch_bounded(1025, |_| {});
    assert_eq!(bounded_pool.capacity(), 2048);
    let retained = bounded_pool.release();
    println!(
        "bounded release: capacity={} -> retained={}",
        2048, retained[0]
    );
    assert_eq!(retained[0], 1025);
    bounded_pool.reset();
    assert_eq!(bounded_pool.release()[0], 0);

    println!("MAX_POOL_SLOTS = {MAX_POOL_SLOTS} (max concurrent nested borrows)");
    println!("all scratch-pool assertions passed");
}

pub fn with_scratch<const INDEX: usize, R>( &self, n: usize, f: impl FnOnce(&mut [T]) -> R, ) -> R

Runs f with scratch from slot INDEX, sized to exactly n elements.

INDEX is a const generic so role selection is resolved at compile time at monomorphized call sites.

Panics

Panics when INDEX >= N.

Examples found in repository

examples/book_scratch_pool.rs (lines 69-72)

fn main() {
    // Construct a pool locally and use it directly (not thread_local! here
    // to avoid the clippy::missing_const_for_thread_local false positive on
    // 1.97.0 — see ATLAS-MNEMOSYNE-CI-1).  In production callers store the
    // pool in thread_local! storage so it persists between calls.
    let f64_pool: ScratchPool<f64> = ScratchPool::new();
    let f32_pool: ScratchPool<f32> = ScratchPool::new();

    // Simple single-level scratch use: compute a dot product via a temp buffer.
    f64_pool.with_scratch(1024, |scratch| {
        for (i, slot) in scratch.iter_mut().enumerate() {
            *slot = i as f64;
        }
        let partial: f64 = scratch.iter().sum();
        println!(
            "sum of 0..1024 via scratch: {} (expected {})",
            partial,
            (0..1024usize).sum::<usize>() as f64,
        );
        assert_eq!(partial, (0..1024usize).sum::<usize>() as f64);
    });

    // Nested borrows: outer scratch holds the signal; inner holds a window.
    f64_pool.with_scratch(256, |signal| {
        for (i, s) in signal.iter_mut().enumerate() {
            *s = (i as f64).sin();
        }
        f64_pool.with_scratch(16, |window| {
            window.copy_from_slice(&signal[..16]);
            let dp = dot_product(window, &signal[..16]);
            println!("windowed dot-product: {dp:.6}");
            assert!(dp.is_finite());
        });
    });

    // F32 pool: same API, different element type.
    f32_pool.with_scratch(64, |buf| {
        buf.fill(1.0_f32);
        let total: f32 = buf.iter().sum();
        println!("f32 scratch sum: {total}");
        assert_eq!(total, 64.0_f32);
    });

    // Banked scratch keeps multiple related roles in one const-generic group,
    // which matches transform pipelines that need independent temporary views
    // without falling back to the system allocator.
    let bank: ScratchBank<f64, 2> = ScratchBank::new();
    bank.with_scratch::<1, _>(32, |scratch| {
        scratch.fill(3.5);
        assert!(scratch.iter().all(|v| *v == 3.5));
    });

    // Bounded provisioning retains the working set while making geometric
    // growth headroom reclaimable at a consumer-selected quiescent point.
    let bounded_pool: ScratchPool<u32> = ScratchPool::new();
    bounded_pool.with_scratch_bounded(1024, |_| {});
    bounded_pool.with_scratch_bounded(1025, |_| {});
    assert_eq!(bounded_pool.capacity(), 2048);
    let retained = bounded_pool.release();
    println!(
        "bounded release: capacity={} -> retained={}",
        2048, retained[0]
    );
    assert_eq!(retained[0], 1025);
    bounded_pool.reset();
    assert_eq!(bounded_pool.release()[0], 0);

    println!("MAX_POOL_SLOTS = {MAX_POOL_SLOTS} (max concurrent nested borrows)");
    println!("all scratch-pool assertions passed");
}

pub fn with_scratch_bounded<const INDEX: usize, R>( &self, n: usize, f: impl FnOnce(&mut [T]) -> R, ) -> R

Like with_scratch, but records the request so a later release can reclaim above the working set. See ScratchPool::with_scratch_bounded for the full contract.

Panics

Panics when INDEX >= N.

pub fn release(&self) -> [[usize; 4]; N]

Reclaims every pool’s storage above its recorded provision. See ScratchPool::release for the contract and the quiescent-calling rhythm this is designed for.

Returns the per-pool, per-slot capacities after reclamation.

pub fn reset(&self)

Clears every pool’s recorded provisions so a later release reclaims every slot entirely. See ScratchPool::reset.

pub fn capacity<const INDEX: usize>(&self) -> usize

Returns the primary capacity for slot INDEX.

Forwards to ScratchPool::capacity and inherits its contract: the figure is readable at any time, including from inside a live Self::with_scratch borrow of the same slot.

Panics

Panics when INDEX >= N.

pub fn slot_capacity<const INDEX: usize>(&self, slot: usize) -> usize

Returns the capacity of slot slot in pool INDEX.

This is the bank-level equivalent of ScratchPool::slot_capacity. It keeps the per-slot mirror visible without requiring a live borrow to the slot itself, which makes hot-loop capacity accounting and warmup tuning easier to reason about while preserving the same zero-copy semantics.

Panics

Panics when INDEX >= N or slot >= MAX_POOL_SLOTS.

pub fn borrow_depth<const INDEX: usize>(&self) -> u8

Returns the current borrow depth for slot INDEX.

Panics

Panics when INDEX >= N.

pub unsafe fn with_scratch_uninit<const INDEX: usize, R>( &self, n: usize, f: impl FnOnce(*mut [T]) -> R, ) -> R

Provides uninitialized scratch from slot INDEX to f.

Like with_scratch but skips the zero- initialization of newly grown capacity. The caller must write every element of the returned slice before reading it.

Safety

Every element of the returned *mut [T] slice must be initialized before any safe read through as_slice, Deref, or similar.

Panics

Panics when INDEX >= N.

pub fn prewarm<const INDEX: usize>(&self, min_capacity: usize)

Prewarms slot INDEX to at least min_capacity elements.

Forwards to ScratchPool::prewarm. No-op when borrowed.

Panics

Panics when INDEX >= N.

pub fn preload(&self, sizes: &[usize])

Batch-prewarms every pool in the bank using the per-pool slot layout.

sizes[i] is interpreted as the minimum capacity for the ith slot of every pool inside this bank. The method mirrors ScratchPool::preload: out-of-range entries are ignored and zero-sized entries are skipped. This lets a caller warm the entire bank in one call while keeping the same single-threaded, zero-copy semantics.

pub fn total_capacity_bytes<const INDEX: usize>(&self) -> usize

Returns the total backing bytes for slot INDEX across all of its slots.

Panics

Panics when INDEX >= N.

pub fn shrink_all_slots(&self)

Releases every slot in every pool without tearing down the bank itself.

This is the bank-level companion to ScratchPool::shrink_all_slots. It is useful for workload boundaries where the allocator should drop all warm scratch allocations before switching to a new transform pipeline.

Trait Implementations

impl<T, const N: usize> Default for ScratchBank<T, N>

where T: ScratchElement,

fn default() -> ScratchBank<T, N>

Returns the “default value” for a type.

impl<T, const N: usize> Send for ScratchBank<T, N>

where T: ScratchElement,