laminar_core/io_uring/
mod.rs

1//! # `io_uring` Advanced Optimization (F067)
2//!
3//! Implements advanced `io_uring` optimizations including SQPOLL mode, registered buffers,
4//! IOPOLL mode, and per-core ring management for sub-microsecond I/O latency.
5//!
6//! ## Features
7//!
8//! - **SQPOLL Mode**: Eliminates syscalls by using a dedicated kernel polling thread
9//! - **Registered Buffers**: Avoids per-operation buffer mapping overhead
10//! - **IOPOLL Mode**: Polls completions directly from `NVMe` queue (no interrupts)
11//! - **Per-Core Rings**: Each core has its own `io_uring` instance for thread-per-core
12//! - **Three-Ring I/O (F069)**: Separate latency/main/poll rings for optimal scheduling
13//!
14//! ## Research Background
15//!
16//! From TU Munich (Dec 2024): Basic `io_uring` yields only 1.06-1.10x improvement,
17//! while careful optimization achieves 2.05x or more.
18//!
19//! ## Platform Support
20//!
21//! This module is Linux-only (`io_uring` requires Linux 5.10+, advanced features need 5.19+).
22//! On other platforms, a no-op fallback is provided.
23//!
24//! ## Example
25//!
26//! ```rust,ignore
27//! use laminar_core::io_uring::{IoUringConfig, CoreRingManager};
28//!
29//! let config = IoUringConfig::builder()
30//!     .ring_entries(256)
31//!     .enable_sqpoll(true)
32//!     .sqpoll_idle_ms(1000)
33//!     .buffer_size(64 * 1024)
34//!     .buffer_count(256)
35//!     .build();
36//!
37//! let mut manager = CoreRingManager::new(0, &config)?;
38//!
39//! // Submit and poll I/O operations
40//! let user_data = manager.submit_read(fd, offset, len)?;
41//! let completions = manager.poll_completions();
42//! ```
43//!
44//! ## Three-Ring I/O (F069)
45//!
46//! For optimal latency/throughput balance, use the three-ring reactor:
47//!
48//! ```rust,ignore
49//! use laminar_core::io_uring::three_ring::{ThreeRingConfig, ThreeRingReactor};
50//!
51//! let config = ThreeRingConfig::builder()
52//!     .latency_entries(256)
53//!     .main_entries(1024)
54//!     .build()?;
55//!
56//! let mut reactor = ThreeRingReactor::new(0, config)?;
57//! // Latency ring for network, main ring for WAL, poll ring for NVMe
58//! ```
59
60mod config;
61mod error;
62
63#[cfg(all(target_os = "linux", feature = "io-uring"))]
64mod buffer_pool;
65#[cfg(all(target_os = "linux", feature = "io-uring"))]
66mod manager;
67#[cfg(all(target_os = "linux", feature = "io-uring"))]
68mod ring;
69#[cfg(all(target_os = "linux", feature = "io-uring"))]
70mod sink;
71#[cfg(all(target_os = "linux", feature = "io-uring"))]
72pub mod three_ring;
73
74pub use config::{IoUringConfig, IoUringConfigBuilder, RingMode};
75pub use error::IoUringError;
76
77#[cfg(all(target_os = "linux", feature = "io-uring"))]
78pub use buffer_pool::RegisteredBufferPool;
79#[cfg(all(target_os = "linux", feature = "io-uring"))]
80pub use manager::{Completion, CompletionKind, CoreRingManager, PendingOp, RingMetrics};
81#[cfg(all(target_os = "linux", feature = "io-uring"))]
82pub use ring::{create_iopoll_ring, create_optimized_ring, IoUringRing};
83#[cfg(all(target_os = "linux", feature = "io-uring"))]
84pub use sink::IoUringSink;
85
86/// Check if `io_uring` is available on this platform.
87#[must_use]
88pub const fn is_available() -> bool {
89    cfg!(all(target_os = "linux", feature = "io-uring"))
90}
91
92/// Get the minimum kernel version required for basic `io_uring` features.
93#[must_use]
94pub const fn min_kernel_version() -> &'static str {
95    "5.10"
96}
97
98/// Get the kernel version required for advanced features (IOPOLL, passthrough).
99#[must_use]
100pub const fn advanced_kernel_version() -> &'static str {
101    "5.19"
102}
103
104#[cfg(test)]
105mod tests {
106    use super::*;
107
108    #[test]
109    fn test_availability() {
110        // This test passes on any platform
111        let _ = is_available();
112    }
113
114    #[test]
115    fn test_kernel_versions() {
116        assert_eq!(min_kernel_version(), "5.10");
117        assert_eq!(advanced_kernel_version(), "5.19");
118    }
119}
laminar_core/io_uring/mod.rs

laminar_core/io_uring/
mod.rs
