Go 运行时(三)：netpoller 如何用 epoll 与 gopark 跑异步 I/O

Table of contents

TL;DR

Go 运行时在创建网络 socket 时将其设为非阻塞，当 Read/Write 返回 EAGAIN 时，通过 gopark 挂起 goroutine（不占 OS 线程），将 fd 注册到 epoll/kqueue（边缘触发），就绪后通过调度器的 findRunnable 或 sysmon 唤醒 goroutine 重试——用户写的是同步代码，运行时跑的是异步 I/O。

1. 解决什么问题

没有 netpoller 会怎样

Go 的并发模型允许轻松创建数十万 goroutine。如果每个 goroutine 执行网络 read() 时直接阻塞 OS 线程（M），10,000 个并发连接就需要 10,000 个 OS 线程——每个线程 1-8MB 栈内存，加上内核调度开销，系统直接崩溃。

netpoller 的解法

将传统 I/O 多路复用（epoll/kqueue/IOCP）封装进运行时，对上层暴露同步 API：

n, err := conn.Read(buf)  // 看起来阻塞了 goroutine

实际执行路径：

1. socket 在创建时已被设为非阻塞模式（syscall.SetNonblock(fd, true)）
2. syscall.Read 返回 EAGAIN（数据未就绪）
3. goroutine 被 gopark 挂起（状态 _Gwaiting），OS 线程被释放去执行其他 goroutine
4. fd 已注册在 epoll 实例上，内核跟踪就绪状态
5. 调度器在 findRunnable 或 sysmon 中调用 epoll_wait，发现 fd 就绪
6. goroutine 被 goready 唤醒，重试 syscall.Read——这次数据已到达

本质：用户写同步代码（可读性好），运行时跑异步 I/O（性能好）。事件循环的复杂性被完全封装在 runtime 中。

2. 三层抽象架构

用户代码
  net.Conn / net.TCPConn           ← 网络连接抽象
    └── net.netFD                  ← 网络元数据（family, sotype, addr）
        └── internal/poll.FD       ← I/O 操作 + 非阻塞重试循环
            └── runtime.pollDesc   ← goroutine 挂起/唤醒 + 截止时间管理
                └── epoll/kqueue   ← OS 级 I/O 多路复用

net.netFD

位于 net/fd_posix.go，持有网络元数据，所有 I/O 委托给 poll.FD：

type netFD struct {
    pfd         poll.FD     // 实际的 I/O 包装器
    family      int         // AF_INET, AF_INET6
    sotype      int         // SOCK_STREAM, SOCK_DGRAM
    isConnected bool
    net         string      // "tcp", "udp"
    laddr       Addr
    raddr       Addr
}

internal/poll.FD

位于 internal/poll/fd_unix.go，核心是非阻塞重试循环：

type FD struct {
    fdmu        fdMutex     // 串行化 Read/Write
    Sysfd       int         // OS 文件描述符
    pd          pollDesc    // netpoller 集成
    csema       uint32      // close 信号量
    isBlocking  uint32      // 是否阻塞模式
    IsStream    bool        // 流式 vs 数据报
    isFile      bool        // 文件 vs 网络 socket
}

FD.Read 的核心逻辑：

func (fd *FD) Read(p []byte) (int, error) {
    if err := fd.readLock(); err != nil { return 0, err }
    defer fd.readUnlock()
    for {
        n, err := ignoringEINTRIO(syscall.Read, fd.Sysfd, p)
        if err == syscall.EAGAIN && fd.pd.pollable() {
            // 数据未就绪 → 挂起 goroutine，等 netpoller 唤醒
            if err = fd.pd.waitRead(fd.isFile); err == nil {
                continue  // 被唤醒后重试 syscall
            }
        }
        return n, err
    }
}

runtime.pollDesc — 核心数据结构

位于 runtime/netpoll.go，每个被 netpoller 管理的 fd 对应一个 pollDesc：

type pollDesc struct {
    link  *pollDesc          // pollCache 空闲链表指针
    fd    uintptr            // 关联的文件描述符

    // --- 无锁状态机 ---
    fdseq      atomic.Uintptr  // 序列号，防止 fd 复用导致的虚假唤醒
    atomicInfo atomic.Uint32   // 打包的状态位（closing/expired/eventErr/fdseq）

    rg atomic.Uintptr  // 读信号量：pdNil → pdWait → G指针 → pdReady
    wg atomic.Uintptr  // 写信号量：同上

    // --- 截止时间管理 ---
    lock mutex
    rd   int64    // 读截止时间（nanotime，-1 表示已过期，0 表示无截止时间）
    wd   int64    // 写截止时间
    rt   timer    // 读截止时间定时器（内联，Go 1.14 起）
    wt   timer    // 写截止时间定时器
    rseq uintptr  // 读定时器序列号，防止过期回调误触发
    wseq uintptr  // 写定时器序列号
}

关键设计：

pollCache — 对象池

type pollCache struct {
    lock  mutex
    first *pollDesc  // 空闲链表头
}

分配策略：

• 批量分配：一次申请 4KB，切分为多个 pollDesc，摊薄分配成本
• 非 GC 内存（persistentalloc）：pollDesc 被 epoll 内核数据结构引用（epoll_event.data 存的是 pollDesc 指针），GC 不能移动或回收它
• 空闲链表复用：连接关闭后 pollDesc 归还链表，不释放内存

3. 完整 I/O 生命周期

以 conn.Read(buf) 为例，从用户代码到内核再回来：

用户: conn.Read(buf)
  │
  ├─ 1. net.TCPConn.Read → netFD.Read → poll.FD.Read
  │     syscall.Read(fd, buf) → EAGAIN（非阻塞 socket，数据未到）
  │
  ├─ 2. fd.pd.waitRead → runtime_pollWait(pd, 'r')
  │     poll_runtime_pollWait 检查错误（closing/timeout），无错则进入 netpollblock
  │
  ├─ 3. netpollblock(pd, 'r', false)
  │     CAS: rg = pdNil → pdWait（标记为等待状态）
  │     gopark(netpollblockcommit, ..., waitReasonIOWait)
  │       ├─ netpollblockcommit: CAS rg = pdWait → G指针，增加 netpollWaiters
  │       └─ goroutine 进入 _Gwaiting 状态，M 被释放去跑其他 G
  │
  ├─ 4. [内核] epoll 监控 fd，数据到达时标记就绪
  │
  ├─ 5. 调度器调用 netpoll()
  │     epoll_wait() 返回就绪事件
  │     → netpollready → netpollunblock: CAS rg = G指针 → pdReady，提取 G
  │     → 返回 gList，调度器 injectglist 将 G 放入运行队列
  │
  ├─ 6. G 被调度执行，gopark 返回
  │     netpollblock 返回 true（old == pdReady）
  │     poll_runtime_pollWait 返回 pollNoError
  │
  └─ 7. FD.Read 的 for 循环 continue
        syscall.Read(fd, buf) → 成功读取数据 → 返回给用户

4. 平台后端实现

统一接口

每个平台必须实现：

func netpollinit()                                // 一次性初始化
func netpollopen(fd uintptr, pd *pollDesc) int32  // 注册 fd
func netpollclose(fd uintptr) int32               // 注销 fd
func netpoll(delta int64) (gList, int32)          // 轮询事件
func netpollBreak()                               // 唤醒阻塞的 netpoll
func netpollIsPollDescriptor(fd uintptr) bool     // 内部 fd 判断

平台对比

为什么用边缘触发

边缘触发（ET）只在状态变化时通知（数据从无到有），不在状态持续时重复通知（缓冲区有未读数据）。Go 的重试循环（读到 EAGAIN 才挂起）保证了正确性。好处：

• 避免 goroutine 还没处理完数据时被重复唤醒
• 减少 epoll_wait 返回的事件数量
• 注册一次即可，不需要每次重新 arm（Solaris 等水平触发平台需要）

fdseq 防虚假唤醒

连接关闭后 OS 可能立即复用同一个 fd 号给新连接。如果旧连接的 epoll 事件还在队列中，会错误唤醒新连接的 goroutine。

解法：epoll_event.data 存的是 pollDesc 指针 | fdseq。事件到达时比较 fdseq，不匹配则静默丢弃。

5. 与 GMP 调度器的集成

netpoll() 的调用时机

netpoll(delay) 参数语义

• delay < 0：无限阻塞，直到有事件
• delay == 0：非阻塞，立即返回
• delay > 0：最多阻塞 delay 纳秒（转换为 epoll_wait 的毫秒参数）

netpollWaiters 优化

netpollWaiters 是原子计数器，追踪当前挂起在 netpoller 上的 goroutine 数量。调度器在调用 netpoll() 前检查 netpollAnyWaiters()——如果为零，跳过 epoll_wait 系统调用，避免无网络 I/O 时的无谓开销。

sched.pollingNet 串行化

findRunnable 中通过 sched.pollingNet 原子变量确保同一时刻只有一个 P 执行 netpoll，避免多核机器上对内核 epoll 实例的竞争。

sysmon 的角色

sysmon 是独立的 M（不需要 P），守护线程方式运行，休眠策略从 20μs 指数增长到最大 10ms：

• 检查距上次 netpoll 是否超过 10ms，超过则触发一次非阻塞 netpoll(0)
• 将就绪的 goroutine 注入全局运行队列
• 这是网络 I/O 不被 CPU 密集型任务饿死的最后保障

6. 截止时间（Deadline）实现

SetReadDeadline 的内部流程

conn.SetReadDeadline(time.Now().Add(5*time.Second))
  → runtime_pollSetDeadline(pd, absoluteNanotime, 'r')
    → 存储 pd.rd = absoluteNanotime
    → 启动内联定时器 pd.rt，回调函数 = netpollReadDeadline
    → 递增 pd.rseq（使旧定时器回调失效）

定时器到期时：

netpollReadDeadline(pd)
  → 检查 pd.rseq 是否匹配（防止已重设的旧截止时间误触发）
  → pd.rd = -1（标记过期）
  → 发布 atomicInfo（设置 pollExpiredReadDeadline 位）
  → netpollunblock(pd, 'r') → 唤醒 goroutine
  → goroutine 在 netpollcheckerr 中发现 pollErrTimeout → 返回 os.ErrDeadlineExceeded

关键陷阱：Deadline 是绝对时间，不是超时时间

conn.SetReadDeadline(time.Now().Add(5 * time.Second))
conn.Read(buf1)  // ✅ 有 5 秒
// ... 过了 3 秒 ...
conn.Read(buf2)  // ⚠️ 只剩 2 秒！不是重新计时 5 秒

想要每次操作都有独立超时，必须在每次 Read/Write 前重设：

for {
    conn.SetReadDeadline(time.Now().Add(5 * time.Second))  // 每次重设
    n, err := conn.Read(buf)
    // ...
}

7. 文件 I/O 为什么不走 netpoller

Linux 的 epoll 不支持普通文件。 对普通文件 fd 调用 epoll_ctl 返回 EPERM。这是内核限制——epoll 只支持 socket、pipe、eventfd 等。

FD.Init() 检测到 fd 不可 poll 时，走阻塞路径：

• syscall.Read 直接阻塞 OS 线程（M）
• 运行时通过 handoff 机制补偿：sysmon 检测到 M 阻塞超过 10ms → 将 P 转交给新 M
• 代价：线程膨胀。高并发文件 I/O 会创建大量 OS 线程

对比：

社区有通过 io_uring 支持异步文件 I/O 的提案（issue #31908），但因 io_uring 的固定大小 submission ring 与 goroutine 的无限增长模型存在架构冲突，目前仍未实现。

8. 与其他运行时对比

9. 历史演进

Pitfalls

1. 文件 I/O 静默阻塞 OS 线程

os.File.Read 不走 netpoller，高并发文件读写会导致线程膨胀。解法：用 worker pool 限制并发文件 I/O 数量。

2. 不设 Deadline 导致 goroutine 泄漏

客户端断网（无 FIN/RST）时，conn.Read 的 goroutine 永远挂在 netpoller 上。必须设置 Deadline。

3. Deadline 是绝对时间不是超时

见第 6 节。每次操作前必须重设，否则后续操作继承已缩短的剩余时间。

4. DNS 解析可能阻塞 OS 线程

cgo resolver（macOS 默认）调用 getaddrinfo，阻塞 OS 线程。限制为 500 并发，但仍可能导致线程膨胀。解法：GODEBUG=netdns=go 强制使用纯 Go resolver（走 netpoller）。

5. CPU 密集型 goroutine 延迟网络事件处理

所有 P 都忙于 CPU 计算时，findRunnable 中的 netpoll(0) 无法被调用。sysmon 的 10ms 兜底保证了网络 G 不会永远饿死，但延迟最高可达 10ms。解法：CPU 密集型任务与 I/O 密集型任务分离，或在计算循环中插入 runtime.Gosched()。

信息来源

• runtime/netpoll.go、runtime/netpoll_epoll.go、runtime/netpoll_kqueue.go — Go 源码（确定）
• internal/poll/fd_unix.go、internal/poll/fd_poll_runtime.go — Go 源码（确定）
• runtime/proc.go（findRunnable、sysmon）— Go 源码（确定）
• Scalable Go Scheduler Design Doc (Dmitry Vyukov, 2012)（确定）
• Go 1.1/1.2/1.14/1.24 Release Notes — go.dev/doc（确定）
• io_uring proposal #31908（确定）