monoio-rs/monoio

Monoio is a cross-platform asynchronous I/O runtime for Rust that provides high-performance networking and file system operations. It supports multiple backends, including io\_uring on Linux, IOCP on Windows, and a legacy mio-based driver for broader compatibility. The system offers comprehensive async primitives for TCP, UDP, Unix sockets, and buffered I/O, along with integration tools for Hyper and Tokio-compatible interfaces.

21 changes.

Monoio achieved cross-platform viability by introducing Windows IOCP support and stable Rust compatibility, replacing the previous io\_uring-only Unix implementation. The runtime expanded its API with comprehensive filesystem, networking, and buffered I/O utilities, while enhancing interoperability through rewritten monoio-compat and Hyper integration.

8 changes.

This period focused on expanding the monoio runtime's core capabilities by implementing high-performance Linux io\_uring and legacy mio/iocp drivers. It also introduced comprehensive async file system operations, including offset-aware I/O and metadata retrieval, alongside refined network features like TCP Fast Open. The work further standardized the API by introducing a new Sink trait and simplifying the Stream trait for easier async/await usage.

The library now includes platform-specific implementations for TCP Fast Open (TFO) to reduce connection latency. On Linux and Android, it sets the TCP\_FASTOPEN socket option for listening and attempts to enable TCP\_FASTOPEN\_CONNECT for outgoing connections, gracefully falling back if the option is unsupported. On macOS and iOS, it enables TCP\_FASTOPEN and uses a platform-specific socket option to force-enable the feature. These changes are gated by the \unstable\ feature flag on Linux.

monoio/src/net/tcp/tfo · high confidence

The library now includes a legacy driver implementation located in \monoio/src/driver/legacy\. This driver provides a \Poll\-like syscall interface for event handling, utilizing \mio\ on Unix systems and \iocp\ on Windows. It supports both async and sync execution modes (via the \sync\ feature) by integrating a waker mechanism to handle task scheduling and unparking, allowing users to run the runtime on platforms or configurations that do not support the primary high-performance drivers.

monoio/src/driver/legacy · high confidence

The \monoio\ library now provides asynchronous \metadata\ and \symlink\_metadata\ functions in the \fs\ module, allowing users to query file attributes (such as type, size, and modification times) without blocking. On Linux, these functions utilize the \statx\ system call to retrieve detailed file information, while macOS falls back to standard \stat\ calls; Windows support is stubbed out. This enables non-blocking inspection of file properties in async contexts.

monoio/src/fs/metadata · high confidence

The \monoio/src/io\ module has been significantly expanded to provide a more comprehensive asynchronous I/O API. New traits \AsyncBufRead\ and \AsyncBufReadExt\ add buffered reading capabilities, including \read\_until\ and \read\_line\ for line-oriented data. Cancellation support is introduced via \CancelableAsyncReadRent\ and \CancelableAsyncWriteRent\, allowing I/O operations to be aborted via a \CancelHandle\. Platform-specific optimizations are added with the \splice\ module (Linux only), enabling efficient zero-copy data transfer between file descriptors. The core \AsyncReadRent\ and \AsyncWriteRent\ traits have been refactored to take \&mut self\ instead of \&self\, and their associated types have been replaced with direct \impl Future\ return types for simpler usage. Additionally, new extension traits provide methods for reading/writing exact amounts of data and primitive types (e.g., \read\_u16\, \write\_all\), and utilities like \BufReader\, \BufWriter\, and \Split\ are now exported from the module.

monoio/src/io · high confidence

The examples directory has been significantly expanded and modernized. New examples demonstrate integration with the \hyper\ HTTP server and client, as well as the \h2\ HTTP/2 library, utilizing the new \poll-io\ feature to bridge completion-based I/O with poll-based interfaces. Additional examples cover TCP Fast Open (\echo\_tfo\), io\_uring-specific TCP streams (\tcp\_uring\), and legacy driver usage (\tcp\_legacy\). Existing examples have been refactored to use the \\#\[monoio::main\]\ macro, explicit driver generics (e.g., \FusionDriver\, \IoUringDriver\), and updated I/O traits (\AsyncReadRent\/\AsyncWriteRent\), while \proxy.rs\ now uses split streams for concurrent reading and writing.

examples · high confidence

The \monoio/src/fs\ module now includes new capabilities for directory and symlink management, adding \DirBuilder\ (with recursive creation), \create\_dir\, \create\_dir\_all\, and \symlink\ functions. It also introduces \FileType\ and \Permissions\ types to expose file metadata and access control details. Under the hood, \OpenOptions\ has been significantly extended to support platform-specific configuration, including Unix mode and custom flags, as well as Windows-specific access modes, share modes, and security attributes. Additionally, the module now provides \read\ and \write\ convenience functions for entire file contents and implements an \asyncify\ helper to offload blocking operations when the \iouring\ feature is not active.

monoio/src/fs · high confidence

Added a new \Sink\ trait for async/await-based output streams, featuring \send\, \flush\, and \close\ methods, along with a \SinkExt\ trait that provides a convenient \send\_and\_flush\ helper. This enables users to write to async sinks with built-in error handling and automatic flushing capabilities.

monoio/src/io/sink · high confidence

The \monoio::fs::File\ type is now available, providing asynchronous file operations that do not maintain an internal cursor, requiring callers to specify explicit offsets for reads and writes via \read\_at\ and \write\_at\. This implementation supports platform-specific optimizations, using io-uring on Linux when available, and falls back to blocking thread-pool execution or simulated vectored I/O on other platforms. It also includes methods to open, create, and close files, as well as retrieve metadata and convert from standard library file handles.

monoio/src/fs/file · high confidence

This change adds a new IoUring driver implementation for the monoio runtime, located in monoio/src/driver/uring. It introduces a lifecycle state machine (lifecycle.rs) that correctly handles multi-completion queue event (CQE) operations, such as zero-copy sends, by tracking intermediate 'MORE' states before final completion. The driver (mod.rs) initializes the io\_uring instance and manages in-flight operations via a slab, while the waker module (waker.rs) implements a custom thread wake mechanism using eventfd to unpark the executor efficiently. This provides a high-performance, native Linux I/O backend for the runtime.

monoio/src/driver/uring · high confidence

The \monoio/src/utils\ module now includes a \CtrlC\ future that allows applications to asynchronously wait for and handle Ctrl+C signals, and a \detect\_uring\ function that checks if the current Linux platform supports the required io\_uring operations (with an option to force the legacy driver via the \MONOIO\_FORCE\_LEGACY\_DRIVER\ environment variable). Additionally, the internal slab allocator has been rewritten to use a page-based structure for cheaper expansion and memory deallocation, and the linked list utility has been updated to expose a \drain\_filter\ method.

monoio/src/utils · high confidence

The library now supports Unix datagram sockets (UnixDatagram) and Unix sequential packet sockets (UnixSeqpacket) on Linux, providing bind, connect, send/recv, and listener functionality. UnixStream gains peer credential inspection via UCred, explicit poll-io readiness checks (readable/writable), and a poll-io style adapter (UnixStreamPoll) for compatibility with tokio's AsyncRead/AsyncWrite traits. UnixListener now supports cancelable accepts, conversion from std types, and readiness polling, while socket address handling is improved for cross-platform correctness.

monoio/src/net/unix · high confidence

This change introduces a new \monoio::io::util\ module providing \BufReader\ and \BufWriter\ for buffered reading and writing, a \Canceller\/\CancelHandle\ system to cancel in-flight I/O operations, a \copy\ utility to transfer data between readers and writers, and a \PrefixedReadIo\ wrapper that allows reading from a prefix buffer before falling through to the underlying stream. It also adds \Split\ and \Splitable\ traits with \OwnedReadHalf\ and \OwnedWriteHalf\ types to safely split I/O streams into independent read and write halves.

monoio/src/io/util · high confidence

The \\#\[main\]\ and \\#\[test\]\ macros now support configuring the runtime driver via a new \driver\ attribute (accepting \legacy\, \uring\, or \fusion\), allowing users to explicitly select the underlying I/O backend. Additionally, a \threads\ (or \worker\_threads\) attribute has been added to specify the number of worker threads; this enforces a constraint that multi-threaded configurations cannot return values. A new \\#\[test\_all\]\ macro has also been introduced to provide a unified testing entry point.

monoio-macros · high confidence

This change introduces a comprehensive set of new operation implementations in the driver's \op\ module, enabling file-system and socket operations on Linux via io\_uring while maintaining support for legacy (poll-based) and Windows backends. Specifically, it adds support for \accept\, \close\, \connect\, \fsync\, \mkdir\, \open\, \poll\, \read\, \recv\, \rename\, \send\, \splice\, \statx\, \symlink\, and \unlink\ operations. Each operation is implemented with platform-specific syscalls (e.g., \io\uring\ opcodes on Linux, \WSA\\ functions on Windows, and standard POSIX calls on other Unix systems) and integrates with the existing \Op\ and \OpAble\ traits to ensure consistent asynchronous execution across different runtime features.

monoio/src/driver/op · high confidence

The runtime now supports executing blocking tasks via the new \spawn\_blocking\ API, which allows offloading heavy computations or blocking I/O to a thread pool (configurable via \DefaultThreadPool\ or a custom implementation) or executing them on the local thread. This feature is gated by the \sync\ feature flag. Additionally, the runtime can now be built with a \LegacyDriver\ (gated by the \legacy\ feature) as an alternative to the default \IoUringDriver\, enabling compatibility with non-io\_uring environments. The \start\ function signature has changed to require a generic driver type parameter, and the scheduler now includes a round-limit to prevent I/O starvation.

monoio/src · high confidence

The \monoio\ driver now supports Windows by introducing a new IOCP-based polling backend (\monoio/src/driver/iocp\), which includes a \Poller\, \CompletionPort\, and AFD-based socket state management. This new Windows-specific code replaces the previous Unix-only \io\_uring\ implementation (evidenced by the deletion of \accept.rs\, \connect.rs\, \read.rs\, \write.rs\, etc., which relied on \io\_uring\ opcodes). The driver now conditionally compiles either the \poll\ (for \poll-io\ feature) or \iocp\ (for Windows) backend, enabling the library to function on Windows systems where \io\_uring\ is unavailable.

monoio/src/driver · high confidence

Users can now create and use UDP sockets via the new \UdpSocket\ type, which supports binding, connecting, and asynchronous send/recv operations. The listener configuration struct has been renamed from \ListenerConfig\ to \ListenerOpts\ (with the old name deprecated), and the default behavior for \reuse\_addr\ has changed from false to true. Additionally, a \tcp\_fast\_open\ option is now available in the listener options.

monoio/src/net · high confidence

Debug logging in the monoio macros now uses the \tracing\ crate instead of \eprintln\, providing structured logging via \trace!\ and \info!\ macros. Additionally, the \pin!\ macro is deprecated in favor of the standard library's \std::pin::pin\, and example code in \select!\ and \join!\ documentation has been updated to reflect this change. A new \scoped\_tls\ module is also added to support scoped thread-local storage.

monoio/src/macros · high confidence

Users can now run Monoio on stable Rust (1.75+) instead of requiring the nightly toolchain, and the runtime supports epoll on Linux and kqueue on macOS in addition to io\_uring, making it viable on older Linux kernels and non-Linux platforms. The project also adopts dual MIT/Apache-2.0 licensing, adds code coverage and formatting configurations, and updates documentation to reflect these broader compatibility options.

(repo-wide) · high confidence

The timing wheel implementation has been refactored to improve efficiency and reduce memory overhead. The internal \Level\ struct now caches \slot\_range\ and \level\_range\ values, allowing the expiration calculation to use faster bitwise masking instead of division and modulo operations. Additionally, the \Wheel\ struct stores its levels in a fixed-size boxed array (\Box\<\[Level; NUM\_LEVELS\]\>\) rather than a \Vec\, and accesses these levels via unchecked bounds checks (\get\_unchecked\_mut\) to eliminate runtime bounds-checking overhead during timer insertion, removal, and polling.

monoio/src/time/driver/wheel · high confidence

The buffer module has been restructured to improve safety and add Windows support. The \IoBuf\ and \IoVecBuf\ traits have been renamed and refined (e.g., \stable\_ptr\ to \read\_ptr\, \stable\_iovec\_ptr\ to \read\_iovec\_ptr\) to clarify pointer semantics, and new implementations have been added for \Box\<\[u8; N\]\>\ and \&'static \[u8; N\]\. The previous \SharedBuf\ and \SliceMut\ types have been removed and replaced with \RawBuf\, \RawBufVectored\, \IoVecWrapper\, and a new \SliceMut\ type that enforces bounds checking. Additionally, the module now supports Windows via \WSABUF\ structures and introduces \MsgBuf\/\MsgMeta\ for handling \msghdr\/\WSAMSG\ structures, enabling vectored I/O on both Unix and Windows.

monoio/src/buf · high confidence

The task runtime's internal mechanics have been restructured to improve reliability and performance when waking tasks across threads. The task state is now managed using atomic operations instead of unsafe cell access, ensuring thread-safe state transitions. Cross-thread wake logic has been consolidated and hardened: it now correctly handles scenarios where the runtime context is not yet initialized by falling back to a default context, and it enforces that cross-thread wakers require the 'sync' feature. Additionally, the \JoinHandle\ now implements \Send\ and \Sync\ (when the output is \Send\), and exposes an \is\_finished\ method for checking task completion without blocking. Debug output has also been migrated from \eprintln\ to the \tracing\ crate for better observability.

monoio/src/task · high confidence

The monoio-compat library has been completely rewritten to provide two distinct compatibility modes for bridging monoio streams to the Tokio AsyncRead/AsyncWrite interface. The previous \TcpStreamCompat\ (which copied data into owned buffers) is replaced by \StreamWrapper\ (exposed as \TcpStreamCompat\ and \UnixStreamCompat\), a safe wrapper that buffers data to prevent issues with pending futures. A new \TcpStreamCompatUnsafe\ type is also introduced, which avoids copying by passing raw pointers directly to the underlying monoio I/O, offering higher performance but requiring the user to guarantee buffer validity until the operation completes. The crate now also includes a \hyper\ module that implements \hyper::rt::Executor\ and \Timer\ using monoio, allowing Hyper-based servers to run on the monoio runtime.

monoio-compat · high confidence

The \monoio::io::stream\ module has been refactored to replace the previous GAT-based (Generic Associated Types) \Stream\ trait with a simpler signature using \impl Future\. This change simplifies the API for users by removing complex lifetime bounds on the \next\ method and associated \Future\ types. Additionally, the \StreamExt::for\_each\ method now correctly awaits the closure provided for each item, ensuring asynchronous operations inside the closure are executed properly, and a blanket implementation allows \&mut S\ to act as a \Stream\ when \S\ is a \Stream\.

monoio/src/io/stream · high confidence

The TCP networking module now supports Windows via new socket handling and address parsing logic, and introduces a poll-io compatibility layer (\TcpStreamPoll\) that implements \tokio::io::AsyncRead\ and \AsyncWrite\ traits for use with legacy drivers. Users can now perform cancelable TCP operations using \CancelHandle\ and configure TCP Fast Open on both client connections (\TcpConnectOpts\) and server listeners (\ListenerOpts\). The split API has been refactored to use owned halves (\TcpOwnedReadHalf\, \TcpOwnedWriteHalf\) that expose standard socket address methods, replacing the previous reference-based split.

monoio/src/net/tcp · high confidence

The time driver internals have been refactored to use standard library pinning and reorganized imports, while the \TimeDriver\ struct no longer requires the \Driver\ trait bound on its generic parameter. Additionally, the \\#\[monoio::main\]\ macro now requires the explicit \timer\_enabled = true\ attribute to activate timer functionality, and the \Driver\ trait implementation for the time driver has been updated to delegate \with\ and \submit\ calls to the underlying driver instance.

monoio/src/time/driver · high confidence

The \monoio::time\ module now explicitly re-exports \TimeDriver\ alongside the existing sleep and timeout types, making the underlying driver accessible to users. Several public APIs have been updated to require the \timer\_enabled = true\ attribute on the \\#\[monoio::main\]\ macro, ensuring timers are properly initialized. Additionally, the \Elapsed\ error type now implements \Eq\, and the \Instant::sub\ operation now uses \checked\_sub\ to handle potential underflow safely. Documentation examples have also been corrected to reflect accurate timing values.

monoio/src/time · high confidence

Added comprehensive integration tests for the monoio runtime's core capabilities. The new test suite validates \AsyncReadRent\ and \AsyncWriteRent\ implementations for mutable slices, boxed writers, and \Cursor\ types, including vectored I/O (\readv\/\writev\) and \BufWriter\ behavior. Filesystem operations are now tested for directory creation (\create\_dir\_all\), file metadata, renaming, symlinks, and unlinking. Networking tests cover TCP listener/stream acceptance, connection establishment, cancellation, and zero-copy send (\write\_zc\) on Linux. Signal handling (\CtrlC\) is verified for both legacy and io\_uring drivers, and file descriptor leak scenarios during cancelled operations are explicitly tested to ensure proper cleanup.

monoio/tests · high confidence

This update bumps the monoio runtime to version 0.2.4 and monoio-compat to 0.2.2, introducing significant dependency upgrades including syn 2.0, socket2 0.5, nix 0.29, and io-uring 0.6. The runtime now supports legacy driver mode via mio for older kernels and macOS, adds experimental poll-io compatibility with tokio, and introduces new file system operations (mkdirat, unlinkat, renameat, symlinkat) and splice support. The examples workspace has been expanded with hyper and h2 client/server demos, and the monoio-compat crate now offers optional hyper integration.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 72 → 69 (-3.0)
• Rubric changed (rubric-2026.09.11 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 96 → 96 (+0.0)
• Architecture 99 → 94 (-4.9)
• Maturity 63 → 58 (-4.8)
• Readiness 69 → 67 (-1.9)
• Security 79 → 79 (+0.0)
• Performance 100 (new)

• Documentation: no project overview (docs/zh/comparing-with-others.md)

• Ambiguous naming for vectored I/O. readv is a standard POSIX name, but read is generic. In the context of AsyncReadRent, it is unclear if read is strictly non-vectored or if it handles both. Furthermore, AsyncWriteRent has write and writev, but AsyncReadRent has read and readv. The inconsistency is minor but the naming readv vs read is less intuitive than read vs read_vectored used in standard Rust futures.
• Confusing naming for conversion vs creation. from_std suggests converting from a standard library type, but the parameter type is Instant (presumably the monoio Instant or a compatible one). If it converts from std::time::Instant, the parameter type should be std::time::Instant to be clear. If it is a copy constructor, it is redundant with new or default construction.
• Dependency hygiene PARTLY measured — Cargo dependencies read, no committed lock to grade for currency
• Documentation: no architecture or design documentation (docs/en/poll-io.md)
• Documentation: no architecture or design documentation (docs/en/use-legacy-driver.md)
• Inconsistent binding API pattern. TcpListener has two distinct bind methods (bind and bind_with_config), whereas UnixListener also has bind and bind_with_config. However, UdpSocket only has bind(addr: A) and no bind_with_config. This inconsistency forces users to check documentation to see if configuration options are available for a specific socket type.
• Inconsistent parameter type for file offset. File uses u64 for position, while the generic AsyncReadRentAt trait uses usize. This forces users to cast offsets when working with types that might implement both or when abstracting over file-like streams.
• Low cohesion: Op (LCOM4 24) (monoio/src/driver/op.rs)
• Low cohesion: StreamWrapper (LCOM4 4) (monoio-compat/src/safe_wrapper.rs)
• Low cohesion: TcpStreamCompat (LCOM4 4) (monoio-compat/src/tcp_unsafe.rs)
• Redundant constructors with unclear safety contract distinction. Both constructors take the same arguments. Typically, new is safe and new_unchecked is unsafe, but here both appear to be available without clear visibility into which is unsafe. If both are safe, new_unchecked is redundant. If one is unsafe, the signature doesn't reflect it (missing unsafe keyword in the method signature provided).
• Semantic mismatch in 'exact' operations. File.read_exact_at implies a fixed-size read to fill the buffer exactly, whereas AsyncReadRentExt.read_exact is a combinator that reads until the buffer is full (potentially multiple syscalls). The naming suggests similar behavior, but the signatures and underlying mechanics differ significantly (one is a direct syscall wrapper, the other is a loop combinator).
• Split monoio

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

monoio-rs/monoio was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.