Module kernel_async_ring 

kernel_async_ring: the kernel async-I/O ring (io_uring on Linux, IoRing on Windows, POSIX aio on FreeBSD / macOS) exposed as a substrate ring primitive.

Both OSes ship the same architecture - a user->kernel SUBMISSION ring and a kernel->user COMPLETION ring - which is exactly the substrate’s SharedRing shape applied to the user/kernel boundary. This wraps that kernel object behind one cross-platform surface; only the ring syscalls are gated, the verb shape (prepare / submit / reap) and the normalized Completion are shared:

• Linux (#[cfg(target_os = "linux")]): io_uring via the mainline io-uring crate (IoUring::new / opcode::Read / submit_and_wait / completion iterator).
• Windows (#[cfg(windows)]): IoRing via windows-sys (CreateIoRing / BuildIoRingReadFile / SubmitIoRing / PopIoRingCompletion), gated on QueryIoRingCapabilities + IsIoRingOpSupported so an unsupported build degrades to Err rather than UB.
• FreeBSD (#[cfg(target_os = "freebsd")]): POSIX aio with kqueue completion. Each aio_read carries an aio_sigevent set to SIGEV_KEVENT against the ring’s kqueue, so completion posts an EVFILT_AIO kevent (ident = the aiocb pointer, udata = the caller’s tag); submit_and_wait is a kevent wait, reap calls aio_return. There is no separate batched submit - aio_read issues each op immediately - but the prepare / wait / reap verb shape is identical.
• macOS (#[cfg(target_os = "macos")]): POSIX aio with aio_suspend completion. Darwin has no SIGEV_KEVENT and its EVFILT_AIO kqueue filter rejects registration, so completion is driven by aio_suspend over the in-flight set rather than a kevent wait; aio_read still does the real kernel async I/O and reap calls aio_return. Same prepare / wait / reap verb shape.

The completion encodings differ - io_uring packs bytes-or--errno into one i32; IoRing splits ResultCode (HRESULT) and Information (bytes); aio reports via aio_error + aio_return - so all three are normalized to a single Completion with an io::Result<usize> byte count.

Structs

Completion

One reaped completion: which submission it answers (user_data, the tag the caller passed to prepare_read) and its result - the number of bytes transferred, or the error the kernel reported.

KernelAsyncRing

A kernel async-I/O ring backed by an io_uring instance.

Functions

open_for_async_read

Open a file for reading through the kernel async ring. On Windows the handle must carry FILE_FLAG_OVERLAPPED for IoRing; on Linux and FreeBSD a plain read handle is fine. Keep the returned File alive while its reads are in flight.