Interface RegisteredBufferPool

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
RegisteredBufferPoolImpl
public interface RegisteredBufferPool extends AutoCloseable
Thread-safe pool for managing pre-registered I/O buffers.

This pool maintains a fixed set of off-heap memory buffers that are pre-registered with the I/O backend (e.g., io_uring) for zero-copy operations. Pre-registration eliminates per-operation kernel address validation, providing significant performance improvements.

Performance Benefits

  • 1.7x throughput improvement with io_uring registered buffers
  • Zero heap allocations during I/O operations (GC-free)
  • Eliminated validation overhead per I/O operation
  • Contiguous memory for improved cache and TLB locality

Pool Sizing Guidelines

  • Buffer count: Should match expected concurrent I/O operations. Typical values: 64-512 for clients, 256-4096 for servers.
  • Buffer size: Should match typical message size plus overhead. Typical values: 4KB-64KB depending on protocol.

Usage Pattern

// Create pool (typically once at startup)
RegisteredBufferPool pool = new RegisteredBufferPoolImpl(256, 65536);
backend.registerBufferPool(pool);

// Acquire buffer for I/O (hot path)
RegisteredBuffer buffer = pool.acquire(); // Blocks if none available
try {
    // Write data to buffer
    buffer.segment().copyFrom(data);
    buffer.limit(data.byteSize());

    // Send using registered buffer (zero-copy)
    backend.send(buffer, token);
} finally {
    // Release is typically done in completion handler
    // buffer.close();
}

Thread Safety

All methods are thread-safe. The pool uses lock-free data structures internally for acquire/release operations to minimize contention.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    RegisteredBuffer
    acquire()
    Acquires a buffer from the pool, blocking if necessary.
    int
    available()
    Returns the number of buffers currently available for acquisition.
    int
    capacity()
    Returns the total number of buffers in the pool.
    void
    close()
    Closes the pool and releases all underlying resources.
    int
    inUse()
    Returns the number of buffers currently in use.
    void
    release(RegisteredBuffer buffer)
    Releases a buffer back to the pool for reuse.
    RegisteredBuffer
    tryAcquire()
    Attempts to acquire a buffer without blocking.

  • Method Details

    • acquire

      RegisteredBuffer acquire()
      Acquires a buffer from the pool, blocking if necessary.

      If no buffers are currently available, this method blocks until one is released by another thread. The returned buffer has been cleared (position=0, limit=capacity).

      Returns:
      a registered buffer ready for use
      Throws:
      IllegalStateException - if the pool is closed
      TransportException - if interrupted while waiting

    • tryAcquire

      RegisteredBuffer tryAcquire()
      Attempts to acquire a buffer without blocking.

      Returns immediately with a buffer if one is available, or null if all buffers are in use. This is useful for non-blocking I/O patterns.

      Returns:
      a registered buffer, or null if none available
      Throws:
      IllegalStateException - if the pool is closed

    • release

      void release(RegisteredBuffer buffer)
      Releases a buffer back to the pool for reuse.

      The buffer is automatically cleared (position reset, limit set to capacity) before being made available for the next acquire. This method is also called automatically when RegisteredBuffer.close() is invoked.

      This method is idempotent; releasing an already-released buffer has no effect.

      Parameters:
      buffer - the buffer to release; must have been acquired from this pool
      Throws:
      IllegalArgumentException - if buffer is not from this pool

    • capacity

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

      This is the fixed capacity set at pool creation time.

      Returns:
      the total buffer count

    • available

      int available()
      Returns the number of buffers currently available for acquisition.

      Note: This value may change immediately after the call returns due to concurrent acquire/release operations.

      Returns:
      the current available buffer count

    • inUse

      int inUse()
      Returns the number of buffers currently in use.

      This equals capacity() - available(). Note: This value may change immediately after the call returns.

      Returns:
      the current in-use buffer count

    • close

      void close()
      Closes the pool and releases all underlying resources.

      After closing:

      • All buffers become invalid (accessing them is undefined behavior)
      • acquire() and tryAcquire() will throw
      • The underlying memory is freed

      This method blocks until all buffers can be reclaimed. Ensure all I/O operations using buffers from this pool have completed before closing.

      Specified by:
      close in interface AutoCloseable