Interface TransportHandler

All Known Implementing Classes:
TransportHandlerAdapter
public interface TransportHandler
Callback interface for handling transport lifecycle and I/O events.

This interface provides event-driven notifications for all transport activities including connection establishment, data reception, send completion, and disconnection. It is the primary way to interact with Transport instances.

Design Principles

  • Zero-allocation: Callbacks receive raw MemorySegment references to avoid copying data. The segment is only valid during the callback.
  • Non-blocking: Callbacks are invoked on the I/O thread. Blocking operations will stall all I/O processing.
  • Token-based tracking: Send operations return tokens that correlate with completion callbacks.

Buffer Lifecycle

The data parameter in onDataReceived(MemorySegment) is a view into the transport's internal buffer. It is only valid for the duration of the callback. To preserve data beyond the callback:

  • Copy the data to your own buffer: data.copyFrom(myBuffer)
  • Process the data inline within the callback

Usage Example

transport.start(new TransportHandler() {
    @Override
    public void onConnected(long token) {
        System.out.println("Connected!");
        // Start sending data or wait for incoming data
    }

    @Override
    public void onDataReceived(MemorySegment data) {
        // Process received data - buffer only valid during this call
        byte[] bytes = data.toArray(ValueLayout.JAVA_BYTE);
        processMessage(bytes);
    }

    @Override
    public void onSendComplete(long token) {
        // Send completed successfully
    }

    // ... other callbacks
});
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    onClosed()
    Called when the transport is closed.
    void
    onConnected(long token)
    Called when a connection is successfully established.
    void
    onConnectionFailed(long token, Throwable cause)
    Called when a connection attempt fails.
    void
    onDataReceived(MemorySegment data)
    Called when data is received from the remote peer.
    void
    onSendComplete(long token)
    Called when a send operation completes successfully.
    void
    onSendFailed(long token, Throwable cause)
    Called when a send operation fails.

  • Method Details

    • onConnected

      void onConnected(long token)
      Called when a connection is successfully established.

      After this callback, the transport is ready for I/O operations. You can begin sending data or the transport will automatically start receiving.

      Parameters:
      token - the token returned by Transport.connect(SocketAddress)

    • onConnectionFailed

      void onConnectionFailed(long token, Throwable cause)
      Called when a connection attempt fails.

      The transport remains in a disconnected state. You may attempt to reconnect by calling Transport.connect(SocketAddress) again.

      Parameters:
      token - the token returned by Transport.connect(SocketAddress)
      cause - the exception describing the failure (e.g., connection refused, timeout)

    • onDataReceived

      void onDataReceived(MemorySegment data)
      Called when data is received from the remote peer.

      Important: The data segment is a view into the transport's internal buffer. It is only valid for the duration of this callback. If you need to preserve the data, copy it to your own buffer before returning.

      The transport automatically posts the next receive operation after this callback returns.

      Parameters:
      data - a read-only view of the received data; valid only during this callback

    • onSendComplete

      void onSendComplete(long token)
      Called when a send operation completes successfully.

      The buffer used for the send has been released back to the pool and may be reused for subsequent operations.

      Parameters:
      token - the token returned by Transport.send(MemorySegment)

    • onSendFailed

      void onSendFailed(long token, Throwable cause)
      Called when a send operation fails.

      Common causes include connection reset, broken pipe, or buffer allocation failure. The associated buffer has been released.

      Parameters:
      token - the token returned by Transport.send(MemorySegment)
      cause - the exception describing the failure

    • onClosed

      void onClosed()
      Called when the transport is closed.

      This is called regardless of whether the close was initiated locally (via Transport.close()) or remotely (peer disconnected). After this callback, the transport is no longer usable.