Pool Infrastructure

The pool infrastructure provides lock-free, zero-allocation object management.

Pool Hierarchy

Pool<T> (interface)
    │
    ├── FreeListPool<T>    - CAS-based lock-free generic pool
    │
    ├── BucketPool<T>      - Size-tiered pool using multiple FreeListPools
    │
    └── MemoryPool          - Specialized pool for FixedMemory

Core Interfaces

Poolable

Any object that can be pooled:

public interface Poolable {
    PoolEntry poolEntry();
    
    default void recycle() {
        poolEntry().recycle();
    }
}

Pool

The main pool interface:

public interface Pool<T extends Poolable> extends AutoCloseable {
    // Allocation
    T allocate();
    T allocate(long requiredSize);  // For sized pools
    
    // Capacity
    long minCapacity();
    long maxCapacity();
    long capacity();
    long available();
    
    // Dynamic sizing
    long grow(long count);
    long contractUnused(long count);
    
    // Monitoring
    PoolMetrics metrics();
}

PoolEntry

Tracks pooled objects with slab memory:

public class PoolEntry {
    Object owner;           // The poolable object
    Pool<?> owningPool;     // Pool this entry belongs to
    PoolEntry next;         // Free-list linkage
    
    // Slab tracking
    SlabAllocator slab;
    MemorySegment segment;
    
    // Lifecycle hooks
    protected void onAllocate() {}
    protected void onRecycle() {}
    protected void onEvict() {}
}

FreeListPool

Lock-free pool using CAS-based free-list:

public class FreeListPool<T extends Poolable> implements Pool<T> {
    private volatile PoolEntry head;  // CAS-based free-list
    
    // Simple factory
    public FreeListPool(PoolSettings settings, Supplier<T> factory);
    
    // Memory-aware factory
    public FreeListPool(PoolSettings settings, PoolableFactory<T> factory);
}

Simple Objects

// Objects that don't need memory allocation
FreeListPool<MyObject> pool = new FreeListPool<>(settings, MyObject::new);

Objects with Memory

// Objects that need memory segments
FreeListPool<Packet> pool = new FreeListPool<>(settings, allocator -> {
    MemorySegment data = allocator.allocate(9000, 8);
    MemorySegment desc = allocator.allocate(128, 8);
    return Packet.ofFixed(DescriptorType.NET, data, desc);
});

The PoolableFactory receives a SegmentAllocator backed by SlabAllocator:

@FunctionalInterface
public interface PoolableFactory<T extends Poolable> {
    T create(SegmentAllocator allocator);
}

BucketPool

Size-tiered pool for variable allocations:

public class BucketPool<T extends Poolable> implements Pool<T> {
    private final FreeListPool<T>[] buckets;
    private final long[] sizes;
    
    // Factory receives size
    @FunctionalInterface
    public interface BucketFactory<T extends Poolable> {
        T create(SegmentAllocator allocator, long bucketSize);
    }
    
    public BucketPool(PoolSettings settings, long[] sizes, BucketFactory<T> factory);
}

Usage

long[] sizes = {64, 1518, 9000, 65536};

BucketPool<Packet> pool = new BucketPool<>(settings, sizes, Packet::ofFixed);

// Allocates from smallest bucket >= requested size
Packet small = pool.allocate(60);    // → 64-byte bucket
Packet normal = pool.allocate(1500); // → 1518-byte bucket
Packet jumbo = pool.allocate(8000);  // → 9000-byte bucket

SlabAllocator

Bulk memory allocation with auto-cleanup:

public class SlabAllocator implements SegmentAllocator, AutoCloseable {
    public SlabAllocator(long segmentSize, int segmentCount);
    
    public MemorySegment allocate(long size, long alignment);
    public void free(MemorySegment segment);
    public boolean hasCapacity();
}

Slab Lifecycle

Pool grows:
    new SlabAllocator(9000, 100)  // 100 segments of 9KB
        ↓
    Single Arena allocates 900KB bulk

Object created:
    slab.allocate() → segment
    outstanding++

Object evicted:
    slab.free(segment)
    outstanding--
    if (outstanding == 0) arena.close()  // Auto-cleanup!

PoolSettings

public class PoolSettings {
    // Capacity
    private int minCapacity = 64;    // Preallocated
    private int maxCapacity = 1024;  // Maximum growth
    
    // Memory
    private long segmentSize = 0;    // 0 = no memory allocation
    
    // Contraction
    private boolean contractionEnabled = false;
    private float contractionThreshold = 0.5f;
}

Configuration Examples

// Fixed-size pool
PoolSettings fixed = new PoolSettings()
    .capacity(1000);  // Sets min=max=1000

// Elastic pool
PoolSettings elastic = new PoolSettings()
    .minCapacity(100)
    .maxCapacity(10000)
    .contractionEnabled(true);

// Memory-backed pool
PoolSettings memoryBacked = new PoolSettings()
    .minCapacity(100)
    .maxCapacity(1000)
    .segmentSize(9000);  // Enables slab allocation

PoolMetrics

public interface PoolMetrics {
    long allocations();
    long releases();
    long exhaustions();
    long growthEvents();
    long contractions();
    long evictions();
    
    // Bucket-specific
    int bucketCount();
    long allocations(int bucketIndex);
}

Monitoring Example

PoolMetrics metrics = pool.metrics();

System.out.printf("Allocations: %d%n", metrics.allocations());
System.out.printf("Releases: %d%n", metrics.releases());
System.out.printf("Exhaustions: %d%n", metrics.exhaustions());
System.out.printf("Utilization: %.1f%%%n", 
    100.0 * (pool.capacity() - pool.available()) / pool.capacity());

Thread Safety

All pool operations are lock-free:

// CAS-based push
private void push(PoolEntry entry) {
    PoolEntry oldHead;
    do {
        oldHead = head;
        entry.next = oldHead;
    } while (!HEAD.compareAndSet(this, oldHead, entry));
}

// CAS-based pop
private PoolEntry pop() {
    PoolEntry oldHead, newHead;
    do {
        oldHead = head;
        if (oldHead == null) return null;
        newHead = oldHead.next;
    } while (!HEAD.compareAndSet(this, oldHead, newHead));
    return oldHead;
}

Multiple threads can allocate and recycle concurrently without locks.