源码地图

主线位置：不在主线上。本页说明两条主线经过的代码分在哪几层、哪些文件，哪个 feature 和 cfg 决定编译进来的是哪一份实现，以及仓库用哪些测试和 CI 任务守住十几个平台。

mio 的代码分两层：上面是平台无关的公开类型，下面是 sys 里每个平台各一份的实现。两层之间没有 trait，靠的是「每个平台模块都导出同名的类型和函数」这个约定，由 cfg 在编译期选一份：

flowchart TB
  lib["lib.rs：入口与 pub use"] --> pub["poll.rs、event/、token.rs、interest.rs、waker.rs"]
  lib --> ios["io_source.rs：IoSource T"]
  lib -.-> netm["net/：net feature"]
  pub --> sysm["sys/mod.rs：按平台选"]
  ios --> sysm
  netm --> sysm
  sysm -->|os-poll 且 Unix| unix["sys/unix"]
  sysm -->|os-poll 且 Windows| win["sys/windows"]
  sysm -->|"os-poll 且 WASI p1"| wasi["sys/wasip1"]
  sysm -->|"没开 os-poll"| shell["sys/shell"]
  unix --> selm["selector：epoll、kqueue、event ports、poll"]

src/ 的平台分层

v1.2.4 的 src/ 一共 61 个 .rs 文件、13 451 行（含文档注释和测试）。按目录分：

平台无关层每个文件的分量：

sys/unix/ 的 4 755 行：

两条主线在 Linux 上经过的代码，几乎全在 poll.rs、io_source.rs、event/、selector/epoll.rs、waker/eventfd.rs 这几个文件里，加起来不到 2 000 行；src/ 的大部分是别的平台和文档。

Cargo.toml：三个 feature

Cargo.toml 第 31 行起：

[features]
# By default Mio only provides a shell implementation.
default = ["log"]

# Enables the `Poll` and `Registry` types.
os-poll = []
# Enables additional OS specific extensions, e.g. Unix `pipe(2)`.
os-ext = [
  "os-poll",
  "windows-sys/Win32_System_Pipes",
  "windows-sys/Win32_Security",
]
# Enables `mio::net` module containing networking primitives.
net = []

[dependencies]
log = { version = "0.4.8", optional = true }

默认只开 log，所以光写 mio = "1.2.4" 得到的是一个什么都做不了的 crate。tokio 依赖 mio 时关掉默认 feature（default-features = false），由自己的 net feature 打开 mio/os-poll、mio/os-ext、mio/net，所以 tokio 下面的 mio 不带 log。

macros.rs：用宏包住 cfg

源码里很少直接写 #[cfg(feature = "...")]，而是用 macros.rs 里的一组宏把一串条目包起来：

/// The `os-poll` feature is enabled.
macro_rules! cfg_os_poll {
    ($($item:item)*) => {
        $(
            #[cfg(feature = "os-poll")]
            #[cfg_attr(docsrs, doc(cfg(feature = "os-poll")))]
            $item
        )*
    }
}

每个宏给包住的每一项都加上同一个 #[cfg]，以及给 docs.rs 用的 doc(cfg(...))（文档里那个「Available on crate feature os-poll only」的标签）。一共六个：

后面是 log! 和包着它的 trace!、warn!、error!。平台的选择不走这些宏，而是直接写 target_os，见下一节。

不开 os-poll：Poll 还在，Poll::new 没了

sys/mod.rs 的最后一段是：

cfg_not_os_poll! {
    mod shell;
    pub(crate) use self::shell::*;

    #[cfg(unix)]
    cfg_any_os_ext! {
        mod unix;
        #[cfg(feature = "os-ext")]
        pub use self::unix::SourceFd;
    }
}

sys/shell 导出和真实平台模块同名的 Selector、Event、Events、event 模块、Waker、tcp、udp、uds，每个函数体都是 os_required!()：

macro_rules! os_required {
    () => {
        panic!("mio must be compiled with `os-poll` to run.")
    };
}

于是平台无关层照常编译：lib.rs 无条件地 pub use poll::{Poll, Registry}，Poll 这个类型一直存在。被 cfg_os_poll! 包住的只有 Poll::new 一个函数：没有它就造不出 Poll，也就拿不到 Registry，register 和 Waker::new 都无从调用。

只开 net、不开 os-poll 时试两件事。依赖：

mio = { version = "=1.2.4", features = ["net"] }

第一个程序调 Poll::new：

use mio::Poll;

fn main() {
  let poll = Poll::new();
  println!("{poll:?}");
}

编译不过（M2 Max、rustc 1.99.0）：

error[E0599]: no associated function or constant named `new` found for struct `mio::Poll` in the current scope
 --> src/bin/poll_new.rs:4:20
  |
4 |   let poll = Poll::new();
  |                    ^^^ associated function or constant not found in `mio::Poll`

For more information about this error, try `rustc --explain E0599`.
error: could not compile `exp-mio-intro-nopoll` (bin "poll_new") due to 1 previous error

报错说的是「Poll 上没有 new」，不是「找不到 Poll」。第二个程序不碰 Poll，只建一个 TcpListener：

use mio::net::TcpListener;

fn main() {
  println!("mio::Poll exists: {}", std::any::type_name::<mio::Poll>());
  let listener = TcpListener::bind("127.0.0.1:0".parse().unwrap());
  println!("bind returned: {:?}", listener.is_ok());
}

能编译，运行时 panic。跑 3 次，除了线程号都一样（cargo 注册表路径缩写成 .../）：

mio::Poll exists: mio::poll::Poll

thread 'main' (2019875) panicked at .../mio-1.2.4/src/sys/shell/tcp.rs:6:5:
mio must be compiled with `os-poll` to run.
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

shell/tcp.rs 第 6 行是 new_for_addr 里的 os_required!()：bind 的第一步建 socket 就停了。所以 net 不开 os-poll 的组合能编译、类型都在，却一调用就 panic。这样设计的用意见下面的框。

If a library is interested only in networking primitives but aims to provide an
other strategy for I/O source readiness polling, there is no way to disable the
provided implementation.

每个平台用哪个 selector

sys/mod.rs 先按大类分：unix、target_os = "hermit" 和 WASI preview 2 及以后走 sys/unix，Windows 走 sys/windows，WASI preview 1 走 sys/wasip1。lib.rs 还拒绝其他 wasm 目标：compile_error!("This wasm target is unsupported by mio. If using Tokio, disable the net feature.")。

sys/unix 里没有 selector/mod.rs。sys/unix/mod.rs 只声明一个 mod selector;，前面叠四个 #[cfg_attr(..., path = "...")]，条件成立的那个决定这个模块实际是哪个文件：

cfg_os_poll! {
    #[cfg_attr(all(
        not(mio_unsupported_force_poll_poll),
        any(
            target_os = "android",
            target_os = "illumos",
            target_os = "linux",
            target_os = "redox",
        )
    ), path = "selector/epoll.rs")]
    // ... kqueue.rs、event_ports.rs、poll.rs 三个同样的 cfg_attr
    mod selector;
    pub(crate) use self::selector::*;

紧接着的下一组 cfg_attr 用同样的办法给 mod waker; 选 Waker 的实现。把两组 cfg_attr 读出来，再加上 Windows 和 WASI p1，合成一张表（不加任何 --cfg 时）：

几处值得留意：

• illumos 用的是 epoll，不是 Solaris 的 event ports；Poll 文档里的表也这么写。Redox 用 epoll 但 Waker 走 pipe。
• 公开的 Waker 在 lib.rs 里是 #[cfg(not(any(target_os = "horizon", target_os = "wasi")))]：这两个平台上 mio::Waker 根本不存在。
• Poll 和 Registry 只在有单个 selector fd 的平台上实现 AsRawFd / AsFd（impl AsRawFd for Poll 前面的 cfg 排除了全部 poll(2) 平台）：poll(2) 实现没有一个能交给别人去等的 fd。
• 本站的两个平台，Linux 走第一行，macOS 走第四行。

mio_unsupported_force_poll_poll 与 mio_unsupported_force_waker_pipe

上表里每个 cfg_attr 都带着 not(mio_unsupported_force_poll_poll)。这是两个不属于任何 feature 的 --cfg 标志，要通过 RUSTFLAGS 传。Cargo.toml 最后两行把它们登记进 check-cfg，免得编译器报「unexpected cfg」：

[lints.rust]
unexpected_cfgs = { level = "warn", check-cfg = ['cfg(mio_unsupported_force_poll_poll)', 'cfg(mio_unsupported_force_waker_pipe)'] }

README 的「Unsupported flags」一节说明了用途和态度：

Current flags:
 * `mio_unsupported_force_poll_poll`, uses an implementation based on `poll(2)`
   for `mio::Poll`.
 * `mio_unsupported_force_waker_pipe`, uses an implementation based on `pipe(2)`
   for `mio::Waker`.

**Again, Mio does not officially supports this**. Furthermore these flags may
disappear in the future.

mio_unsupported_force_poll_poll 打开时：所有平台的 selector 都换成 selector/poll.rs；kqueue 平台的 Waker 换成 pipe（sys/unix/mod.rs 的注释：「kqueue(2) based waker doesn't work with poll(2)」）；Linux 上 Waker 仍是 eventfd。上面的最小程序用 RUSTFLAGS="... --cfg mio_unsupported_force_poll_poll" 重新编译，在 Linux 容器里跑（Linux 6.12.28（Apple container 里的 Alpine，aarch64 musl 静态链接）、rustc 1.99.0，strace -f -e trace=epoll_create1,epoll_ctl,epoll_pwait,ppoll,poll,eventfd2,pipe2,accept4,read,write，标准输出重定向掉）。3 次除端口和栈地址外逐行相同，其中一次：

ppoll([{fd=0, events=0}, {fd=1, events=0}, {fd=2, events=0}], 3, {tv_sec=0, tv_nsec=0}, NULL, 8) = 0 (Timeout)
eventfd2(0, EFD_CLOEXEC|EFD_NONBLOCK)   = 3
write(3, "\1\0\0\0\0\0\0\0", 8)         = 8
read(3, "\1\0\0\0\0\0\0\0", 8)          = 8
ppoll([{fd=3, events=POLLIN}, {fd=4, events=POLLIN|POLLRDHUP}], 2, NULL, NULL, 8) = 1 ([{fd=4, revents=POLLIN}])
write(1, "poll 1: token=Token(7) readable="..., 52) = 52
accept4(4, {sa_family=AF_INET, sin_port=htons(46236), sin_addr=inet_addr("127.0.0.1")}, [128 => 16], SOCK_CLOEXEC|SOCK_NONBLOCK) = 6
write(1, "accept: ok\n", 11)            = 11
accept4(4, 0xffffd21b7538, [128], SOCK_CLOEXEC|SOCK_NONBLOCK) = -1 EAGAIN (Resource temporarily unavailable)
write(3, "\1\0\0\0\0\0\0\0", 8)         = 8
read(3, "\1\0\0\0\0\0\0\0", 8)          = 8
write(1, "accept: WouldBlock\n", 19)    = 19
strace: Process 4 attached
[pid     3] ppoll([{fd=3, events=POLLIN}, {fd=4, events=POLLIN|POLLRDHUP}], 2, NULL, NULL, 8 <unfinished ...>
[pid     4] write(3, "\1\0\0\0\0\0\0\0", 8 <unfinished ...>
[pid     3] <... ppoll resumed>)        = 1 ([{fd=3, revents=POLLIN}])
[pid     4] <... write resumed>)        = 8
[pid     3] read(3, "\1\0\0\0\0\0\0\0", 8) = 8
[pid     3] write(1, "poll 2: token=Token(9) readable="..., 52) = 52
[pid     4] +++ exited with 0 +++
write(3, "\1\0\0\0\0\0\0\0", 8)         = 8
read(3, "\1\0\0\0\0\0\0\0", 8)          = 8
+++ exited with 0 +++

程序的标准输出和 epoll 版一样，但系统调用完全换了一套：没有一个 epoll_*；register 没有对应的内核调用，fd 列表由 mio 在用户态维护，每次 poll 都把整个列表交给 ppoll；整个进程只有一个 eventfd（fd 3），既用来叫醒正在 ppoll 的线程，也是用户 Waker 的事件来源；accept4 返回 EAGAIN 之后紧跟着一对 write(3) / read(3)，那是 do_io 在把 listener 重新放回关注集合。第一行 ppoll 查的是 fd 0、1、2，那是 Rust 标准库启动时检查标准输入输出是否打开，和 mio 无关。这些机制在 poll(2) 后备一章逐项讲。

这个标志对上层也有影响。tokio 的 PollEvented::poll_read 有一个「读不满就说明已经读空」的优化，只在 epoll 和 kqueue 上成立，它的 cfg 里就写着 not(mio_unsupported_force_poll_poll)；来历见从 TcpStream::read 到挂起。tokio 的 Cargo.toml 也把这个 cfg 登记进了自己的 check-cfg。

mio_unsupported_force_waker_pipe 只换 Waker：eventfd 平台和 kqueue 平台都改用 pipe 版。

tests/：17 个测试文件

tests/ 下每个文件编译成一个独立的测试程序。几乎每个文件开头都有 #![cfg(all(feature = "os-poll", feature = "net"))]，所以要 cargo test --all-features 才跑得到：

发布的包里没有 tests/：Cargo.toml 的 include 只列了 Cargo.toml、LICENSE、README.md、CHANGELOG.md、src/**/*.rs、examples/**/*.rs。想对照本页读测试，要看 git 仓库。

CI：哪些平台真跑测试，哪些只编译

.github/workflows/ci.yml 在 v1.2.4 有 18 个任务。按「在哪个平台上跑了什么」整理：

合并 PR 要求通过的 Passed 任务只依赖其中 11 个：Test、TestPoll、MinimalVersions、MSRV、Nightly、Clippy、Docs、Rustfmt、Miri、CheckTier1、TestFreeBSD。TestWakerPipe、TestWASI、Sanitizer、TestSolaris、Wine 和 CheckTier2 失败不挡合并；Solaris 是 1.2.3 发版前的提交「Remove testing Solaris from CI pass requirement」从这个列表里拿掉的。

也就是说，真正跑测试的平台是 Linux、macOS、Windows、FreeBSD、Solaris、Wine 和 WASI p2；其余平台只保证编译通过。本站的两个平台都在第一行里，每个 PR 都跑。

小结

• src/ 13 451 行：平台无关层 2.6k、net/ 2.3k、sys/unix 4.8k（四个 selector 占 2.6k）、sys/windows 3.0k。Linux 上两条主线经过的代码不到 2 000 行。
• 两层之间没有 trait：每个平台模块导出同名的 Selector、Event、Events、Waker、IoSourceState，sys/unix/mod.rs 用 #[cfg_attr(..., path = "...")] 在编译期挑一个文件当 mod selector。
• feature 默认只有 log；os-poll 决定 Poll::new 在不在，net 给网络类型，os-ext 给 pipe、SourceFd、NamedPipe。不开 os-poll 时类型都在，Poll::new 编译报 E0599，网络类型落到 sys/shell，一调用就 panic「mio must be compiled with os-poll to run.」（#1192，0.7.0 起）。tokio 用 default-features = false 加 os-poll、os-ext、net。
• Linux、Android、illumos 用 epoll，Apple 系统和四个 BSD 用 kqueue，Solaris 用 event ports，其余 Unix 用 poll(2)，Windows 用 IOCP + AFD。--cfg mio_unsupported_force_poll_poll 把所有平台换成 poll(2)，strace 里 epoll_* 全部变成 ppoll。
• CI 在 Linux、macOS、Windows、FreeBSD 上跑测试并挡合并，poll(2) 后备和 Miri 也挡合并；Solaris、Wine、WASI 跑但不挡；CheckTier1 / CheckTier2 的 40 个目标只做编译检查。