Class MyraServerConfig

java.lang.Object
express.mvp.myra.server.MyraServerConfig
public class MyraServerConfig extends Object
Configuration for a MyraServer instance.

This class uses the builder pattern to configure all aspects of the server, including network binding, buffer pool settings, and io_uring-specific options like SQPOLL mode and CPU affinity.

Configuration Categories

Configuration options by category
CategoryOptionsDescription
Networkhost, portSocket binding address
Buffer PoolnumBuffers, bufferSizeRegistered buffer configuration
CPU AffinitycpuAffinity, sqPollCpuAffinityCore pinning for NUMA optimization
SQPOLLsqPollEnabled, sqPollIdleTimeoutKernel-side SQ polling mode

Usage Example

MyraServerConfig config = MyraServerConfig.builder()
    .host("0.0.0.0")
    .port(8080)
    .numBuffers(2048)
    .bufferSize(8192)
    .cpuAffinity(0)
    .sqPollEnabled(true)
    .sqPollCpuAffinity(1)
    .sqPollIdleTimeout(1000)
    .build();

SQPOLL Mode Considerations

When SQPOLL is enabled, a dedicated kernel thread continuously polls the submission queue, eliminating system call overhead for submitting I/O operations. This provides the lowest latency but consumes CPU even when idle (until the idle timeout triggers). For best results:

  • Pin the SQPOLL thread to a dedicated core (sqPollCpuAffinity)
  • Set the server thread to a different core (cpuAffinity)
  • Tune sqPollIdleTimeout based on traffic patterns
See Also:

  • Method Details

    • getHost

      public String getHost()
      Returns the host address to bind to.
      Returns:
      the host address (e.g., "0.0.0.0" or "127.0.0.1")

    • getPort

      public int getPort()
      Returns the TCP port to listen on.
      Returns:
      the port number (1-65535)

    • getNumBuffers

      public int getNumBuffers()
      Returns the number of registered buffers in the pool.

      This determines the maximum concurrent I/O operations that can use zero-copy buffers. Should be sized based on expected concurrent connections and in-flight operations per connection.

      Returns:
      the number of buffers

    • getBufferSize

      public int getBufferSize()
      Returns the size of each buffer in bytes.

      Should be sized to accommodate the largest expected message plus framing overhead. Common values are 4096 (4KB) or 8192 (8KB).

      Returns:
      the buffer size in bytes

    • getCpuAffinity

      public int getCpuAffinity()
      Returns the CPU core affinity for the server thread.

      Setting CPU affinity pins the server thread to a specific core, improving cache locality and reducing context switch overhead.

      Returns:
      the CPU core index, or -1 if no affinity is set

    • getSqPollCpuAffinity

      public int getSqPollCpuAffinity()
      Returns the CPU core affinity for the SQPOLL kernel thread.

      When SQPOLL is enabled, the kernel creates a dedicated thread that continuously polls the submission queue. Pinning this thread to a dedicated core prevents interference with the server thread.

      Returns:
      the CPU core index, or -1 if no affinity is set

    • isSqPollEnabled

      public boolean isSqPollEnabled()
      Returns whether SQPOLL mode is enabled.

      SQPOLL mode eliminates system call overhead by having a kernel thread continuously poll the submission queue. This provides the lowest latency but uses CPU even when idle.

      Returns:
      true if SQPOLL mode is enabled
      See Also:

    • getSqPollIdleTimeout

      public int getSqPollIdleTimeout()
      Returns the SQPOLL idle timeout in microseconds.

      When SQPOLL is enabled and no new submissions are made within this timeout, the kernel thread goes to sleep and will be woken by the next submission (requiring a system call). Lower values keep the thread active longer; higher values reduce CPU usage during idle periods.

      Returns:
      the idle timeout in microseconds

    • builder

      public static MyraServerConfig.Builder builder()
      Creates a new builder for constructing MyraServerConfig instances.
      Returns:
      a new builder with default values