Class TcpTransport

java.lang.Object
express.mvp.myra.transport.TcpTransport
All Implemented Interfaces:
Transport, AutoCloseable
public final class TcpTransport extends Object implements Transport
TCP-based implementation of Transport using a pluggable I/O backend.

This is the primary transport implementation, providing asynchronous TCP communication with zero-copy I/O support via registered buffers.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      TcpTransport                           │
├─────────────────────────────────────────────────────────────┤
│  Application Thread         │        Poller Thread          │
│  ─────────────────         │        ─────────────           │
│  • connect()               │        • pollLoop()            │
│  • send()                  │        • processCommands()     │
│  • acquireBuffer()         │        • backend.poll()        │
│           │                │               │                │
│           ▼                │               ▼                │
│   ┌───────────────┐        │       ┌─────────────┐          │
│   │ Command Queue │───────────────▶│  Backend    │          │
│   │  (MPSC Ring)  │        │       │ (io_uring)  │          │
│   └───────────────┘        │       └─────────────┘          │
└─────────────────────────────────────────────────────────────┘

Thread Model

  • Application threads: Submit commands via lock-free MPSC queue
  • Poller thread: Processes commands, submits to kernel, polls completions

Token-Based Correlation

Operations are tracked using 64-bit tokens with the following bit layout:

  • Bit 63: Receive operation flag
  • Bit 62: Connect operation flag
  • Bits 0-61: Monotonically increasing sequence number

CPU Affinity

If configured, the poller thread is pinned to a specific CPU core for reduced latency variance and improved cache locality.

See Also:

  • Constructor Details

    • TcpTransport

      public TcpTransport(TransportBackend backend, RegisteredBufferPool bufferPool, SocketAddress remoteAddress, int cpuAffinity)
      Creates a new TCP transport with the specified backend and configuration.
      Parameters:
      backend - the I/O backend to use
      bufferPool - the registered buffer pool
      remoteAddress - the remote endpoint to connect to
      cpuAffinity - CPU core to pin poller thread (-1 for no affinity)

  • Method Details

    • start

      public void start(TransportHandler handler)
      Description copied from interface: Transport
      Starts the transport with the specified handler for receiving callbacks.

      This method must be called before any I/O operations. The handler receives all completion callbacks (connect, send, receive, errors).

      Lifecycle: After calling start, the transport is ready for I/O. Call Transport.close() to shut down cleanly.

      Specified by:
      start in interface Transport
      Parameters:
      handler - the callback handler for I/O completion events

    • connect

      public long connect(SocketAddress remoteAddress)
      Description copied from interface: Transport
      Initiates an asynchronous connection to a remote endpoint.

      The connection attempt runs asynchronously. When complete, the TransportHandler.onConnected(long) callback is invoked with the result (0 for success, negative errno for failure).

      Token Usage

      The returned token is passed to the completion handler and can be used to correlate this operation with application-level state.

      Specified by:
      connect in interface Transport
      Parameters:
      remoteAddress - the remote address to connect to (e.g., InetSocketAddress)
      Returns:
      a token identifying this operation for correlation in completion callbacks
      See Also:

    • send

      public long send(MemorySegment data)
      Description copied from interface: Transport
      Sends data asynchronously.

      The send operation is queued and executed asynchronously. For best performance, use buffers obtained from Transport.acquireBuffer() which enables zero-copy I/O.

      Memory Ownership: The caller retains ownership of the data segment. The data is copied (or pinned for zero-copy) before this method returns, so the segment can be reused immediately.

      Specified by:
      send in interface Transport
      Parameters:
      data - the memory segment containing data to send
      Returns:
      a token identifying this operation for correlation in completion callbacks
      See Also:

    • acquireBuffer

      public RegisteredBuffer acquireBuffer()
      Description copied from interface: Transport
      Acquires a registered buffer for zero-copy I/O.

      Registered buffers are pre-validated by the kernel, eliminating per-operation address validation overhead. This provides approximately 1.7x throughput improvement with io_uring.

      Blocking Behavior: This method blocks if no buffers are available until one is released.

      Resource Management: Always release buffers via RegisteredBuffer.close() when done, typically in a try-with-resources block.

      Specified by:
      acquireBuffer in interface Transport
      Returns:
      a registered buffer from the pool, ready for use
      See Also:

    • availableBufferSpace

      public int availableBufferSpace()
      Description copied from interface: Transport
      Returns the number of buffers currently available in the pool.

      This can be used to implement backpressure or monitoring. Note that the value may change immediately after the call returns.

      Specified by:
      availableBufferSpace in interface Transport
      Returns:
      the number of available buffers

    • getConnectionPool

      public ConnectionPool getConnectionPool()
      Description copied from interface: Transport
      Returns the connection pool managing connections for this transport.

      The connection pool tracks active connections and provides metrics about connection state.

      Specified by:
      getConnectionPool in interface Transport
      Returns:
      the connection pool (never null)

    • getHealth

      public TransportHealth getHealth()
      Description copied from interface: Transport
      Returns health metrics for this transport.

      Health information includes buffer utilization, error rates, and throughput metrics.

      Specified by:
      getHealth in interface Transport
      Returns:
      transport health information (never null)

    • isConnected

      public boolean isConnected()
      Description copied from interface: Transport
      Checks if the transport has an active connection.
      Specified by:
      isConnected in interface Transport
      Returns:
      true if connected to a remote endpoint

    • getLocalAddress

      public SocketAddress getLocalAddress()
      Description copied from interface: Transport
      Returns the local socket address.
      Specified by:
      getLocalAddress in interface Transport
      Returns:
      the local address, or null if not bound

    • getRemoteAddress

      public SocketAddress getRemoteAddress()
      Description copied from interface: Transport
      Returns the remote socket address.
      Specified by:
      getRemoteAddress in interface Transport
      Returns:
      the remote address, or null if not connected

    • close

      public void close()
      Description copied from interface: Transport
      Closes the transport and releases all resources.

      This method:

      • Closes all active connections gracefully
      • Releases the buffer pool
      • Shuts down the I/O backend
      • Frees all off-heap memory

      After closing, the transport cannot be reused. Create a new instance if needed.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Transport