Expand documentation, cleanup code

mfio/Cargo.toml

@@ -8,6 +8,9 @@ license = "MIT"
 repository = "https://github.com/memflow/mfio"
 description = "memflow completion-based I/O primitives"
 
+[package.metadata.docs.rs]
+features = ["default", "tokio", "async-io"]
+
 [lib]
 bench = false
 
@@ -33,7 +36,7 @@ spin = "0.9"
 nix = { version = "0.26", features = ["poll"] }
 # incompatible with miri
 tokio = { version = "1", optional = true, features = ["net"] }
-async-io = { version = "1", optional = true }
+async-io = { version = "2", optional = true }
 
 [target.'cfg(windows)'.dependencies]
 windows-sys = { version = "0.48", features = ["Win32_System_Threading", "Win32_Foundation", "Win32_Security"] }
@@ -45,5 +48,5 @@ pollster = "0.2"
 bytemuck = { version = "1", features = ["derive"] }
 
 [features]
-default = []#["std", "http"]
+default = ["std", "http"]
 std = ["parking_lot"]

mfio/src/backend/integrations/async_io.rs

@@ -1,5 +1,11 @@
+//! `async-io` 2.0 integration.
+//!
+//! We technically support `async-io` 1, however, the system had a
+//! [limitation](https://github.com/smol-rs/async-io/issues/132) that was only resolved in version
+//! 2.
+
 use async_io::Async;
-use std::os::fd::RawFd;
+use std::os::fd::BorrowedFd;
 
 use super::super::*;
 use super::{BorrowingFn, Integration};
@@ -26,7 +32,7 @@ enum AsyncIoState<'a, B: IoBackend + ?Sized + 'a, Func, F> {
     Initial(Func),
     Loaded(
         WithBackend<'a, B::Backend, F>,
-        Option<(Async<RawFd>, &'a PollingFlags, Waker)>,
+        Option<(Async<BorrowedFd<'a>>, &'a PollingFlags, Waker)>,
     ),
     Finished,
 }
@@ -76,12 +82,10 @@ impl<'a, B: LinksIoBackend + 'a, Func: BorrowingFn<B::Link>> Future
                                  waker,
                                  ..
                              }| {
+                                let handle = unsafe { BorrowedFd::borrow_raw(handle) };
                                 (
-                                    // FIXME: we need to make `Async` not set nonblocking mode, as it
-                                    // is unsupported on kqueues. We should talk with upstream to
-                                    // enable our usage.
-                                    // Async::with_nonblocking_mode(h, false)
-                                    Async::new(handle).expect("Could not register the IO resource"),
+                                    Async::new_nonblocking(handle)
+                                        .expect("Could not register the IO resource"),
                                     cur_flags,
                                     waker,
                                 )

mfio/src/backend/integrations/mod.rs

@@ -1,3 +1,11 @@
+//! Integrates `mfio` backends with other async runtimes.
+//!
+//! Integrations allow `mfio` backend objects to be used in other runtimes with true cooperation.
+//!
+//! Note that the current integration use is rather limited, mainly, both `tokio` and `async-io`
+//! require unix platforms, since async equivalents for windows raw handle polling is not exposed
+//! at the moment.
+
 #[cfg(all(unix, feature = "async-io"))]
 pub mod async_io;
 pub mod null;

mfio/src/backend/integrations/null.rs

@@ -1,3 +1,9 @@
+//! A null integration.
+//!
+//! This integration assumes external wakers, and no backend dependence on cooperative handles.
+//! This works great whenever the I/O backend runs on a separate thread, however, this usually
+//! leads to severe latency penalty due to cross-thread synchronization.
+
 use super::super::*;
 use super::{BorrowingFn, Integration};
 

mfio/src/backend/integrations/tokio.rs

@@ -1,3 +1,5 @@
+//! `tokio` integration.
+
 use std::os::fd::RawFd;
 use tokio::io::{unix::AsyncFd, Interest};
 

mfio/src/backend/mod.rs

@@ -1,3 +1,9 @@
+//! Backends for `mfio`.
+//!
+//! A backend is a stateful object that can be used to resolve a future to completion, either by
+//! blocking execution, or, exposing a handle, which can then be integrated into other asynchronous
+//! runtimes through [integrations].
+
 #[cfg(not(feature = "std"))]
 use crate::std_prelude::*;
 
@@ -327,6 +333,10 @@ impl PollingFlags {
     }
 }
 
+/// Primary trait describing I/O backends.
+///
+/// This trait is implemented at the outer-most stateful object of the I/O context. A `IoBackend`
+/// has the opportunity to expose efficient ways of driving said backend to completion.
 pub trait IoBackend<Handle: Pollable = DefaultHandle> {
     type Backend: Future<Output = ()> + Send + ?Sized;