Memory Types

The Memory Package provides two memory types optimized for different scenarios.

FixedMemory

Memory with a permanently bound segment, allocated from slab pools.

public final class FixedMemory extends AbstractMemory {
    private final MemorySegment segment;  // Final - never changes
    
    public FixedMemory(MemorySegment segment);
}

Characteristics

• Segment bound once at construction, never rebound

• Data boundaries (start/end) are mutable for headroom/tailroom

• Used with pools for packet buffers that persist

Lifecycle

Pool Creation:
    SlabAllocator allocates bulk memory
        ↓
    new FixedMemory(segment)  ← Bound permanently
        ↓
    Added to pool free-list

Hot Path:
    pool.allocate() → FixedMemory
        ↓
    Reset start/end bounds only (NO rebinding)
        ↓
    Use for packet processing
        ↓
    packet.recycle() → back to free-list

When to Use

• Pool-allocated packet buffers

• Copied packet data that outlives native buffers

• Any scenario where memory persists across operations

ScopedMemory

Memory wrapper for externally-provided segments from native backends.

public final class ScopedMemory extends AbstractMemory {
    private MemorySegment segment;  // Mutable - changes per bind
    
    public void bind(MemorySegment segment, long offset, long length);
    public void unbind();
}

Characteristics

• Segment can be rebound to different native memory

• Used for zero-copy packet processing

• Bind/unbind cycle per packet in capture path

Zero-Copy Pattern

Native packet arrives (DPDK mbuf):
    scopedMemory.bind(nativeSegment, offset, length)
        ↓
    Process packet (zero-copy access to native memory)
        ↓
    scopedMemory.unbind()
        ↓
    Return mbuf to native driver

When to Use

• Zero-copy capture from DPDK, Napatech, etc.

• When packet data doesn't need to persist

• Maximum performance scenarios

Comparison

Aspect	FixedMemory	ScopedMemory
Segment	Final, never changes	Rebindable
Allocation	From slab pools	External (native backend)
Hot path	Bounds reset only	Full bind/unbind
Use case	Copied packets	Zero-copy capture
Persistence	Data persists	Data transient

AbstractMemory Base Class

Both types extend AbstractMemory which provides:

public abstract class AbstractMemory implements Memory, Poolable {
    protected final AtomicInteger refCount = new AtomicInteger(1);
    protected final MemoryView memView = new MemoryView();
    protected volatile long dataStart;
    protected volatile long dataEnd;
    
    // Reference counting
    public int incrementRef();
    public int decrementRef();
    
    // Boundary management
    public long start();
    public long start(long newStart);
    public long end();
    public long end(long newEnd);
    
    // View access
    public MemoryView view();
}

PoolEntry Integration

Both memory types implement Poolable:

private final PoolEntry poolEntry = new PoolEntry() {
    @Override
    public void onRecycle() {
        // Reset boundaries
        dataStart = segmentOffset;
        dataEnd = segmentOffset + segmentSize;
        next = null;
        updateView();
    }
};

This enables seamless pool integration - memory objects can be recycled without affecting their bound segments (for FixedMemory) or can have segments unbound (for ScopedMemory).