Struct ThreadLocalPool 

pub struct ThreadLocalPool { /* private fields */ }

Thread-local fast packet pool for zero-contention packet building.

This pool uses thread-local storage to cache packet builders, falling back to a shared ArrayQueue when the local cache is empty. This design:

• Eliminates atomic operations on the hot path (when local cache is warm)
• Maintains fairness through periodic returns to shared pool
• Auto-refills from shared pool in batches to amortize atomic costs

Performance

When the local cache is warm, acquire() and release() have zero atomic operations, making them ~10-15% faster than the shared pool under contention.

Nonce Safety

All builders in the pool (including those in thread-local caches) share a single TX counter. This prevents nonce reuse when different threads encrypt with the same key.

Implementations

impl ThreadLocalPool

pub const DEFAULT_LOCAL_CAPACITY: usize = 8

Default number of builders to cache per thread

pub fn new(size: usize, key: &[u8; 32], session_id: u64) -> Self

Create a new thread-local pool

pub fn with_origin( size: usize, key: &[u8; 32], session_id: u64, origin_hash: u64, ) -> Self

Create a new thread-local pool with origin identity

pub fn with_local_capacity( size: usize, key: &[u8; 32], session_id: u64, origin_hash: u64, local_capacity: usize, ) -> Self

Create a new thread-local pool with custom local capacity

pub fn acquire(&self) -> PacketBuilder

Acquire a builder from the pool.

First tries the thread-local cache (zero atomics), then falls back to the shared pool, refilling the local cache in batches.

pub fn release(&self, builder: PacketBuilder)

Release a builder back to the pool.

Keeps builders in the thread-local cache up to local_capacity * 2, then returns excess to the shared pool.

pub fn capacity(&self) -> usize

Get the pool capacity

pub fn shared_available(&self) -> usize

Get the number of builders in the shared pool

pub fn session_id(&self) -> u64

Get the session ID

pub fn local_capacity(&self) -> usize

Get the local capacity per thread

impl ThreadLocalPool

pub fn get(&self) -> ThreadLocalPooledBuilder<'_>

Get a builder with RAII guard

Trait Implementations

impl Debug for ThreadLocalPool

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

Formats the value using the given formatter.