neton-io
A coroutine-native, high-performance async I/O framework for Kotlin/Native, and the shared
I/O foundation for the Neton stack.
- The architecture follows the ntex-io buffered filter model, mapped onto Kotlin
coroutines.
geario (the ntex network layer extracted into one crate) is the reference.
- It backs long-lived connections/RPC and, later, HTTP — a path to dropping the Rust
Tokio+Hyper engine and unifying the stack on Kotlin/Native.
- Performance target: the strongest Go networking libraries (gnet, netpoll); ntex/geario
as the reference ceiling.
See SPEC.md for the full design.
Artifact
One artifact, com.netonstream:io, the way tokio is one crate. It is a new coordinate with its own version line
starting at 0.1.0; the older com.netonstream:neton-io:0.1.0 is a different, earlier artifact. Packages keep the layering:
neton.io.bytes — growable byte buffer (moves to native/pinned memory later)
neton.io.codec — Decoder/Encoder and LineCodec
neton.io.core — IoStream / Filter / Io / Framed / Service / dispatcher / Readiness
neton.io.net — the reactor over TCP. Readiness drivers: kqueue (Apple), epoll and poll (Linux), java.nio Selector (JVM). Completion driver: io_uring (Linux). Selectable via NETON_IO_DRIVER
dependencies { implementation("com.netonstream:io:0.4.1") }
Targets: macOS, iOS, Linux (x64/arm64), Android native, Windows (mingwX64, IOCP and WSAPoll drivers) and the
JVM.
0.4.1 (2026-10-20). SocketAddress.toString prints IPv6 in RFC 5952 form ([::1]:443), and the formatter is
public as formatIpAddress(bytes, scopeId) for consumers that format raw address bytes.
0.3.3 (2026-10-09). lookupHost(host, port): resolve a name to SocketAddresses (tokio net::lookup_host) for
protocols that dial addresses themselves (UDP, QUIC); literals inline, names off the reactor (SPEC §35). Built with
Kotlin 2.4.20 (SPEC §34), so consumers compile with 2.4.20 or later.
0.3.2 (2026-10-08). UDP receives up to 32 datagrams per call on Windows and Apple too (a WSARecvMsg / recvmsg
loop in the shims, as recvmmsg does on Linux; SPEC §29.9): per received datagram IOCP 13.7 → 0.9 µs, WSAPoll 23–33 →
2.3–2.7 µs; a 4 MiB QUIC transfer on Windows WSAPoll 436–895 → 146–154 ms. NETON_IO_UDP_BATCH overrides the batch.
0.3.1 (2026-10-08). On Windows a read that ends because the peer dropped the connection (WSAECONNABORTED,
ERROR_NETNAME_DELETED, ERROR_CONNECTION_ABORTED) counts as a connection reset, as ECONNRESET does elsewhere.
0.3.0 (2026-10-08). UDP on Windows on both drivers (quinn-udp's windows.rs: WSARecvMsg / WSASendMsg, ECN,
PKTINFO, USO; SPEC §29.7) and 1 ms timer resolution while a Windows reactor runs (SPEC §29.8). CI passes on every
platform for the first time (SPEC §33): IOCP index and accept fixes, bounded Windows sends with exact accounting of
cancelled writes, a reactor that a fast external poster could keep from stopping, Winsock errors taken inside each
call, and io_uring setup retries. The native artifacts are klibs, so a consumer compiles with the release's Kotlin version (2.4.20 from the next release on; 0.3.2 and earlier were built
with 2.4.0).
JVM (2026-10-03). The reactor core, timers, cross-thread dispatch, lifecycle, TCP layer, ReactorGroup,
serveTcp and the public API are the same code as on native; only the driver differs: NioReactor, a
readiness driver over java.nio.channels.Selector (epoll on Linux and Android, kqueue on macOS), with one-shot
interest and the same parking, cancellation, timeout, fairness, idle-sweep and close rules as the native
readiness driver. It uses no native code, bytecode 1.8 and only APIs Android has had since API 21, so an Android
app or library can depend on it. Not available on the JVM: UDP and Unix sockets, signal handling
(shutdownOnSignal, serveTcp(shutdownOnSignals = true) throws — the VM owns the signals), thread pinning, the
GC tuning hooks, keepalive timings (keepalive on/off only; the JDK has no portable API for idle / interval /
probes), and SO_REUSEPORT load balancing (AcceptMode.ReusePort falls back to hand-off). The native readiness
driver is untouched by the port: it stays in nativeMain with its pinned zero-copy data path.
Design
- Coroutine-native, not an actor framework. The public API is
suspend/Flow. Per-connection
ownership (one coroutine, pinned to one reactor thread, share-nothing) gives the lock-free
serialization that an actor mailbox would, without the ceremony.
- The reactor is the scheduler. It doubles as the
CoroutineDispatcher; a coroutine blocked
on I/O parks on an fd and is resumed when the poller reports readiness. The loop blocks in
kevent/epoll_wait when idle — no busy polling.
- Readiness and completion share one
Reactor. Readiness drivers (kqueue/epoll/poll) wait for
the fd then do the syscall; the completion driver (io_uring) submits the op with its buffer and
awaits the result. The upper layers are written against the same suspend read/write/accept.
- TLS is a filter. It slots in as a layer between the socket and the codec.
Build and test
./gradlew macosArm64Test # macOS (Apple Silicon), kqueue reactor
./gradlew linuxX64Test # Linux, epoll reactor
Run the full Linux suite on a Linux host (needed for the io_uring/epoll/poll drivers), pinning the
driver:
# on a Linux host with JDK 17 (the macOS box cannot run the Linux reactors)
NETON_IO_DRIVER=iouring ./gradlew :io:linuxX64Test # io_uring
NETON_IO_DRIVER=epoll ./gradlew :io:linuxX64Test # epoll
NETON_IO_DRIVER=iouring NETON_IO_URING_DEPTH=8 ./gradlew :io:linuxX64Test # full-SQ path
Status
P0 (model + in-memory driver) and P1 (kqueue/epoll reactor + non-blocking TCP) are green;
the io_uring completion driver, the threading contract (cross-thread dispatch + wakeup, owner
checks), reactor timers, and the buffer-lifecycle / close / cancel paths are implemented.
Verified (2026-09-13), reproducible: neton-io linuxX64Test (13 cases) passes with 0
failures on a Rocky Linux 9.8 / kernel 5.14 / x86_64 host under io_uring, epoll, poll(2), and
io_uring at SQ depth 8 (Kotlin 2.4.0, Gradle 8.14.2, JDK 17); macOS (kqueue) passes the same
cases. This is test-case pass, not a guarantee that every error path, scalability, tail latency or
memory behaviour is covered. Windows: core modules compile; the net driver (IOCP) is not built.
JVM (2026-10-03): 116 cases pass on JDK 17 (./gradlew :io:jvmTest), the portable part of the suite moved to
commonTest — TCP echo, timeouts, writev, fairness, idle reads, admission, multi-reactor groups, cross-thread
dispatch and cancellation, posts racing a reactor's close — and the same cases still pass on macOS and the iOS
simulator (154 each). The cross-thread cases also passed 40 rounds under full CPU contention.
Next (P2/P3): TLS filter and WebSocket codec; then io_uring optimization (batching, registered
buffers, multi-reactor) and IOCP, and an HTTP layer.
Benchmark
Raw byte echo (echoServer/echoClient), client and server on the same host, localhost,
release build, 64 B payload, single reactor. The CI bench job runs a short version on every push.
| Platform / driver |
1 conn |
50 conns |
200 conns |
| macOS kqueue (Apple Silicon) |
46,305 |
110,606 |
105,799 req/s |
| Linux epoll (2-core) |
25,192 |
90,181 |
79,451 req/s |
| Linux poll(2) (2-core) |
— |
93,736 |
75,572 req/s |
| Linux io_uring (2-core) |
— |
77,973 |
71,352 req/s |
poll(2) is O(n) per call, so it edges ahead at low connection counts and falls behind epoll as
the fd set grows. The read/write path is allocation-free — the socket fills and drains the
Buffer backing directly. The levers to peak, in order:
- Arm once, edge-triggered — remove the per-round
epoll_ctl re-arm.
- Multi-reactor — one reactor per core with connection affinity.
- io_uring — batched submission, completion-based, registered buffers.
# select the driver at runtime (Linux): NETON_IO_DRIVER=epoll|polling
./echoServer 0.0.0.0 9000
./echoClient 127.0.0.1 9000 50 5 64 # host port connections seconds payload
License
Apache License 2.0.