laminar_core/io_uring/
mod.rs

1//! # `io_uring` Advanced Optimization
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**: 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
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;
69pub use config::{IoUringConfig, IoUringConfigBuilder, RingMode};
70pub use error::IoUringError;
71
72#[cfg(all(target_os = "linux", feature = "io-uring"))]
73pub use buffer_pool::RegisteredBufferPool;
74#[cfg(all(target_os = "linux", feature = "io-uring"))]
75pub use manager::{Completion, CompletionKind, CoreRingManager, PendingOp, RingMetrics};
76#[cfg(all(target_os = "linux", feature = "io-uring"))]
77pub use ring::IoUringRing;
78
79/// Check if `io_uring` is available on this platform.
80#[must_use]
81pub const fn is_available() -> bool {
82    cfg!(all(target_os = "linux", feature = "io-uring"))
83}
84
85/// Get the minimum kernel version required for basic `io_uring` features.
86#[must_use]
87pub const fn min_kernel_version() -> &'static str {
88    "5.10"
89}
90
91/// Get the kernel version required for advanced features (IOPOLL, passthrough).
92#[must_use]
93pub const fn advanced_kernel_version() -> &'static str {
94    "5.19"
95}
96
97#[cfg(test)]
98mod tests {
99    use super::*;
100
101    #[test]
102    fn test_availability() {
103        // This test passes on any platform
104        let _ = is_available();
105    }
106
107    #[test]
108    fn test_kernel_versions() {
109        assert_eq!(min_kernel_version(), "5.10");
110        assert_eq!(advanced_kernel_version(), "5.19");
111    }
112}
laminar_core/io_uring/mod.rs

laminar_core/io_uring/
mod.rs
