Class LockFreeBufferPool

java.lang.Object
express.mvp.myra.transport.buffer.LockFreeBufferPool
All Implemented Interfaces:
AutoCloseable
public class LockFreeBufferPool extends Object implements AutoCloseable
Lock-free buffer pool using a ring buffer for index tracking.

This pool provides high-performance buffer allocation without locks, using a MPSC ring buffer to track free buffer indices.

Memory Layout

The pool allocates a single contiguous "slab" of memory and slices it into individual buffers. This provides several benefits:

  • TLB efficiency: Contiguous memory uses fewer TLB entries
  • Cache locality: Sequential buffers are cache-line adjacent
  • Simple registration: Single memory region for io_uring registration
  • Alignment: 64-byte cache-line alignment for all buffers

Lock-Free Design

The pool uses a lock-free ring buffer for tracking free indices:

  • Acquire: Atomically poll an index from the ring
  • Release: Atomically offer an index back to the ring
  • No contention: MPSC design optimizes for common patterns

Usage Example

LockFreeBufferPool pool = new LockFreeBufferPool(256, 65536);

BufferRef buf = pool.acquire();
if (buf != null) {
    try {
        // Use buffer...
        buf.segment().setAtIndex(...);
        buf.length(dataLen);
    } finally {
        buf.release(); // Auto-returns to pool
    }
}

Power of 2 Requirement

The pool count must be a power of 2 for efficient ring buffer operations (enables bit-masking instead of modulo for index wrapping).

See Also:

  • Constructor Details

    • LockFreeBufferPool

      public LockFreeBufferPool(int count, int bufferSize)
      Creates a new lock-free buffer pool.
      Parameters:
      count - the number of buffers (must be a power of 2)
      bufferSize - the size of each buffer in bytes
      Throws:
      IllegalArgumentException - if count is not a power of 2

  • Method Details

    • acquire

      public BufferRef acquire()
      Acquires a buffer from the pool.

      The returned buffer has refCount=1 and length=0. This method is non-blocking and lock-free.

      Returns:
      a BufferRef with refCount=1, or null if pool is empty

    • capacity

      public int capacity()
      Returns the total capacity of the pool.
      Returns:
      the number of buffers in the pool

    • available

      public int available()
      Returns the number of currently available buffers.
      Returns:
      the available buffer count

    • close

      public void close()
      Closes the pool and releases all memory.

      After closing, all buffers become invalid. Ensure no buffers are in use before calling close.

      Specified by:
      close in interface AutoCloseable