karmaio

A modern, fast, share-nothing asynchronous runtime for Rust, using io_uring on Linux, IOCP on Windows, and kqueue on macOS and BSDs.

Feature flags

Heavy subsystems are opt-in via Cargo features. The core runtime (Runtime, tasks, timers, io traits, buffers, and the platform driver) is always available. No features are enabled by default.

Recommended dependency lines

# Full public API (apps / demos).
karmaio = { version = "0.1.0", features = ["full"] }

# Core runtime only.
karmaio = "0.1.0"

# Networking + attribute macros.
karmaio = { version = "0.1.0", features = ["macros", "net"] }

# Filesystem + signals.
karmaio = { version = "0.1.0", features = ["fs", "signal"] }

# TCP and batteries-included Rustls TLS.
karmaio = { version = "0.1.0", features = ["macros", "net", "tls"] }

TLS

karmaio::tls drives Rustls directly over Karmaio's owned-buffer I/O traits. The tls convenience feature selects ring, TLS 1.3, and TLS 1.2; applications can instead select tls-ring or tls-aws-lc-rs, with optional tls12. TLS does not imply net or bytes.

Applications own verification policy. Supply an Arc<ClientConfig> or Arc<ServerConfig> with an explicit cryptographic provider, trust roots, identity, SNI, and ALPN policy. Karmaio does not install a global provider, discover roots, or offer an insecure verifier.

TLS streams preserve the completion model and add no Send requirement. When the transport implements IntoOwnedSplit, client and server TLS streams produce independently progressing owned halves without an async mutex. Split reads leave protocol-generated output for the next write, flush, or shutdown; matching halves can be reunited when the transport implements ReuniteOwned. Vectored I/O operates directly on caller components, and successful scalar and vectored writes are write-through. Adapter-owned ciphertext buffers have fixed capacity, while Rustls retains its default internal buffering policy. Graceful shutdown sends close_notify. A raw transport EOF without peer close_notify is reported as UnexpectedEof after buffered plaintext is delivered. into_parts is abrupt, performs no TLS or transport shutdown, and refuses to extract state after either direction fails.

Cancellation scopes propagate to the underlying operation and return caller buffers through BufResult. For established I/O, request cancellation and await the same future instead of dropping a timed-out future when buffer recovery matters. If an established I/O future is dropped in flight, later stream operations fail closed because transport progress is ambiguous. Dropping a split write half without calling shutdown is an abrupt TLS close. See the workspace tls_client, tls_split_client, and tls_server examples.

Linux multishot I/O (6.12+)

On Linux, karmaio exposes explicit multishot and managed-buffer APIs (io_uring). There is no kernel version probe; callers must meet the 6.12+ floor.

Classic read / recv with user-owned buffers and BufResult remain unchanged.

Buffer pool and leases

Managed receives use a per-runtime provided buffer pool (defaults: 64 buffers × 8192 bytes, configured via RuntimeBuilder::buffer_pool_size / buffer_pool_buffer_len).

• karmaio::buf::PooledBuf is a lease, not an owned allocation: drop it or call release() to return the slot to the pool.
• Holding many leases without recycling can exhaust the pool; multishot streams then end with ENOBUFS (surfaced as an error item, then stream end). Multishot requests are not auto-rearmed — call recv_multi again after recycling if needed.
• The pool is shared by all sockets on one runtime; retaining leases for one socket can starve unrelated sockets.

See the module docs on karmaio::buf and the echo_tcp_recv_multi example.

License

Licensed under either the Apache License, Version 2.0 or the MIT License, at your option.