Interface CompletionHandler

All Known Subinterfaces:

IoUringBackend.ExtendedCompletionHandler

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface CompletionHandler

Callback interface for handling completion of asynchronous I/O operations.

This is the primary callback interface for receiving notifications when io_uring or NIO operations complete. It follows a zero-allocation design pattern critical for high-frequency trading (HFT) and low-latency applications.

Design Principles

• Allocation-free: Implementations must not allocate objects during callbacks to avoid GC pauses on the hot path
• Token-based tracking: The token correlates completions with their originating operations without object references
• Unified result model: Positive results indicate bytes transferred, negative results indicate Linux errno codes

Result Interpretation

Result value meanings

Result	Meaning
> 0	Success: number of bytes transferred
0	Success with no data (e.g., connect completed)
-1	EOF: peer closed connection
< -1	Error: negated Linux errno (e.g., -104 = ECONNRESET)

Usage Example

CompletionHandler handler = (token, result) -> {
    if (result >= 0) {
        System.out.println("Operation " + token + " transferred " + result + " bytes");
    } else if (result == -1) {
        System.out.println("Connection closed");
    } else {
        System.err.println("Error: errno=" + (-result));
    }
};

backend.poll(handler);

See Also:

• IoUringBackend.ExtendedCompletionHandler
• ErrnoHandler

Method Summary

Modifier and Type	Method	Description
void	onComplete(long token, int result)	Called when an asynchronous I/O operation completes.

Method Details

onComplete

void onComplete(long token,
 int result)

Called when an asynchronous I/O operation completes.

Thread Safety: This method is called from the I/O polling thread. Implementations must be thread-safe if the handler is shared across threads.

Performance: This method is on the hot path. Avoid allocations, blocking calls, or expensive computations.

Parameters:

token - the user-defined token passed when the operation was initiated; use this to correlate completions with pending operations

result - the operation result:

• Positive: bytes transferred
• Zero: operation completed with no data
• -1: EOF (peer closed connection)
• Negative: Linux errno (use -result to get errno value)