hiver_runtime/driver/
mod.rs

1//! Driver module for async I/O operations
2//! 异步I/O操作的Driver模块
3//!
4//! This module provides the driver abstraction layer for different I/O polling mechanisms:
5//! - io-uring (Linux 5.1+)
6//! - epoll (Linux)
7//! - kqueue (macOS/BSD)
8//!
9//! 本模块提供不同I/O轮询机制的driver抽象层：
10//! - io-uring (Linux 5.1+)
11//! - epoll (Linux)
12//! - kqueue (macOS/BSD)
13
14pub mod config;
15pub mod epoll;
16pub mod interest;
17#[cfg(target_os = "linux")]
18pub mod iouring;
19pub mod kqueue;
20pub mod queue;
21
22pub use config::{DriverConfig, DriverConfigBuilder, DriverFactory, DriverType};
23pub use interest::Interest;
24pub use queue::{CompletionEntry, IoState, SubmitEntry};
25
26use std::os::fd::AsRawFd;
27
28/// Core driver trait for async I/O operations
29/// 异步I/O操作的核心driver trait
30///
31/// This trait abstracts different I/O polling mechanisms (io-uring, epoll, kqueue)
32/// providing a unified interface for the runtime.
33///
34/// 此trait抽象了不同的I/O轮询机制（io-uring、epoll、kqueue），
35/// 为运行时提供统一接口。
36pub trait Driver: Send + Sync + AsRawFd {
37    /// Submit queued operations to the kernel
38    /// 将队列中的操作提交给内核
39    ///
40    /// Returns the number of operations submitted.
41    /// 返回已提交的操作数量。
42    fn submit(&self) -> std::io::Result<usize>;
43
44    /// Wait for completion events indefinitely
45    /// 无限等待完成事件
46    ///
47    /// Returns the number of completion events available.
48    /// 返回可用的完成事件数量。
49    fn wait(&self) -> std::io::Result<usize>;
50
51    /// Wait for completion events with a timeout
52    /// 带超时等待完成事件
53    ///
54    /// Returns `(events_count, timed_out)` where:
55    /// - `events_count`: number of completion events / 完成事件数量
56    /// - `timed_out`: true if timeout occurred, false if events arrived / 是否超时
57    fn wait_timeout(&self, duration: std::time::Duration) -> std::io::Result<(usize, bool)>;
58
59    /// Get a mutable reference to the next available submission entry
60    /// 获取下一个可用提交条目的可变引用
61    ///
62    /// Returns `None` if the submission queue is full.
63    /// 如果提交队列已满则返回 `None`。
64    fn get_submission(&self) -> Option<&mut SubmitEntry>;
65
66    /// Get a reference to the next available completion entry
67    /// 获取下一个可用完成条目的引用
68    ///
69    /// Returns `None` if the completion queue is empty.
70    /// 如果完成队列为空则返回 `None`。
71    fn get_completion(&self) -> Option<&CompletionEntry>;
72
73    /// Advance the completion queue cursor, consuming the current entry
74    /// 前进完成队列游标，消费当前条目
75    fn advance_completion(&self);
76
77    /// Register interest in a file descriptor
78    /// 注册对文件描述符的兴趣
79    ///
80    /// This tells the driver to monitor the FD for specific events.
81    /// 这告诉driver监控文件描述符的特定事件。
82    fn register(&self, fd: std::os::fd::RawFd, interest: Interest) -> std::io::Result<()>;
83
84    /// Deregister interest in a file descriptor
85    /// 取消对文件描述符的兴趣注册
86    fn deregister(&self, fd: std::os::fd::RawFd) -> std::io::Result<()>;
87
88    /// Modify the interest for a registered file descriptor
89    /// 修改已注册文件描述符的兴趣
90    fn modify(&self, fd: std::os::fd::RawFd, interest: Interest) -> std::io::Result<()>;
91
92    /// Get the capacity of the submission queue
93    /// 获取提交队列的容量
94    fn submission_capacity(&self) -> usize;
95
96    /// Get the capacity of the completion queue
97    /// 获取完成队列的容量
98    fn completion_capacity(&self) -> usize;
99
100    /// Check if the driver supports the specified operation
101    /// 检查driver是否支持指定操作
102    fn supports_operation(&self, opcode: u8) -> bool;
103}
104
105/// Raw file descriptor type
106/// 原始文件描述符类型
107pub type RawFd = std::os::fd::RawFd;
108
109/// Error code for transport errors
110/// 传输错误的错误码
111pub const ERROR_TRANSPORT: i32 = -1;
112
113/// Operation opcodes
114/// 操作操作码
115pub mod opcode {
116    /// Read operation / 读操作
117    pub const READ: u8 = 0;
118    /// Write operation / 写操作
119    pub const WRITE: u8 = 1;
120    /// Fsync operation / 同步操作
121    pub const FSYNC: u8 = 2;
122    /// Close operation / 关闭操作
123    pub const CLOSE: u8 = 4;
124}
hiver_runtime/driver/mod.rs

hiver_runtime/driver/
mod.rs
