Man page - epoll(7)

Packages contains this manual

Available languages:

en fr ja ru zh_TW zh_CN

Manual

EPOLL

名 称
概 要
说 明
水 平 触 发 与 边 缘 触 发
系 统 自 动 睡 眠 的 处 理
/proc 接 口
示 例 ： 建 议 的 使 用 epoll 的 方 式
epoll 十 问
可 能 的 陷 阱 和 避 免 的 方 法
版 本
适 用 于
注
另 请 参 阅
跋

名 称

epoll - I/O 事 件 通 知 设 施

概 要

#include <sys/epoll.h>

说 明

epoll API 的 任 务 与 poll (2) 类 似 ： 监 控 多 个 文 件 描 述 符 ， 找 出 其 中 可 以 进 行 I/O 的 文 件 描 述 符 。 epoll API 既 可 以 作 为 边 缘 触 发 （ edge-triggered） 的 接 口 使 用 ， 也 可 以 作 为 水 平 触 发 （ level-triggered） 的 接 口 使 用 ， 并 能 很 好 地 扩 展 ， 监 视 大 量 文 件 描 述 符 。

epoll API 的 核 心 概 念 是 epoll 实 例 （ epoll instance ） ， 这 是 内 核 的 一 个 内 部 数 据 结 构 ， 从 用 户 空 间 的 角 度 看 ， 它 可 以 被 看 作 一 个 内 含 两 个 列 表 的 容 器 ：

•

兴 趣 列 表 （ interest list， 有 时 也 称 为 epoll 集 （ epoll set） ） ： 进 程 注 册 了 “监 控 兴 趣 ”的 文 件 描 述 符 的 集 合 。

•

就 绪 列 表 （ ready list） ： “准 备 好 ”进 行 I/O 的 文 件 描 述 符 的 集 合 。 就 绪 列 表 是 兴 趣 列 表 中 的 文 件 描 述 符 的 子 集 （ 或 者 更 准 确 地 说 ， 是 其 引 用 的 集 合 ） 。 内 核 会 根 据 这 些 文 件 描 述 符 上 的 I/O 活 动 动 态 地 填 充 就 绪 列 表 。

下 列 系 统 调 用 可 用 于 创 建 和 管 理 epoll 实 例 ：

•

epoll_create (2) 会 创 建 一 个 新 的 epoll 实 例 ， 并 返 回 一 个 指 向 该 实 例 的 文 件 描 述 符 。 （ 最 新 的 epoll_create1 (2) 扩 展 了 epoll_create (2) 的 功 能 。 ）

•

epoll_ctl (2) 能 向 epoll 实 例 的 兴 趣 列 表 中 添 加 项 目 ， 注 册 对 特 定 文 件 描 述 符 的 兴 趣 。

•

epoll_wait (2) 会 等 待 I/O 事 件 ， 如 果 当 前 没 有 事 件 可 用 ， 则 阻 塞 调 用 它 的 线 程 。 （ 此 系 统 调 用 可 被 看 作 从 epoll 实 例 的 就 绪 列 表 中 获 取 项 目 。 ）

水 平 触 发 与 边 缘 触 发

epoll 事 件 的 分 发 接 口 既 可 以 表 现 为 边 缘 触 发 （ ET） ， 也 可 以 表 现 为 水 平 触 发 （ LT） 。 这 两 种 机 制 的 区 别 描 述 如 下 。 假 设 发 生 下 列 情 况 ：

1.

读 取 方 在 epoll 实 例 中 注 册 代 表 管 道 读 取 端 （ rfd ） 的 文 件 描 述 符 。

2.

写 入 方 在 管 道 的 写 入 端 写 入 2 kB 的 数 据 。

3.

读 取 方 调 用 epoll_wait (2)， rfd 作 为 一 个 就 绪 的 文 件 描 述 符 被 返 回 。

4.

读 取 方 只 从 rfd 中 读 取 1 kB 的 数 据 。

5.

读 取 方 再 次 调 用 epoll_wait (2)。

如 果 读 取 方 添 加 rfd 到 epoll 接 口 时 使 用 了 EPOLLET （ 边 缘 触 发 ） 标 志 位 ， 那 么 纵 使 此 刻 文 件 输 入 缓 冲 区 中 仍 有 可 用 的 数 据 （ 剩 余 的 1 KB 数 据 ） ， 步 骤 5 中 的 epoll_wait (2) 调 用 仍 可 能 会 挂 起 ； 与 此 同 时 ， 写 入 方 可 能 在 等 待 读 取 方 对 它 发 送 的 数 据 的 响 应 。 造 成 这 种 互 相 等 待 的 情 形 的 原 因 是 边 缘 触 发 模 式 只 有 在 被 监 控 的 文 件 描 述 符 发 生 变 化 时 才 会 递 送 事 件 。 因 此 ， 在 步 骤 5 中 ， 读 取 方 最 终 可 能 会 为 一 些 已 经 存 在 于 自 己 输 入 缓 冲 区 内 的 数 据 一 直 等 下 去 。 在 上 面 的 例 子 中 ， 由 于 写 入 方 在 第 2 步 中 进 行 了 写 操 作 ， rfd 上 产 生 了 一 个 事 件 ， 这 个 事 件 在 第 3 步 中 被 读 取 方 消 耗 了 。 但 读 取 方 在 第 4 步 中 进 行 的 读 操 作 却 没 有 消 耗 完 整 个 缓 冲 区 的 数 据 ， 因 此 在 第 5 步 中 对 epoll_wait (2) 的 调 用 可 能 会 无 限 期 地 阻 塞 。

使 用 EPOLLET 标 志 位 的 应 用 程 序 应 当 使 用 非 阻 塞 的 文 件 描 述 符 ， 以 避 免 （ 因 事 件 被 消 耗 而 ） 使 正 在 处 理 多 个 文 件 描 述 符 的 任 务 因 阻 塞 的 读 或 写 而 出 现 饥 饿 。 将 epoll 用 作 边 缘 触 发 （ EPOLLET ） 的 接 口 ， 建 议 的 使 用 方 法 如 下 ：

a)

使 用 非 阻 塞 的 文 件 描 述 符 ；

b)

只 在 read (2) 或 write (2) 返 回 EAGAIN 后 再 等 待 新 的 事 件 。

相 较 而 言 ， 当 作 为 水 平 触 发 的 接 口 使 用 时 （ 默 认 情 况 ， 没 有 指 定 EPOLLET ） ， epoll 只 是 一 个 更 快 的 poll (2)， 可 以 用 在 任 何 能 使 用 poll (2) 的 地 方 ， 因 为 此 时 两 者 的 语 义 相 同 。

即 使 是 边 缘 触 发 的 epoll ， 在 收 到 多 个 数 据 块 时 也 可 能 产 生 多 个 事 件 ， 因 此 调 用 者 可 以 指 定 EPOLLONESHOT 标 志 位 ， 告 诉 epoll 在 自 己 用 epoll_wait (2)收 到 事 件 后 禁 用 相 关 的 文 件 描 述 符 。 当 指 定 了 EPOLLONESHOT 标 志 位 时 ， 调 用 者 可 使 用 epoll_ctl (2) 与 EPOLL_CTL_MOD 标 志 位 重 装 （ rearm） 一 个 被 禁 用 的 文 件 描 述 符 ， 这 是 调 用 者 而 不 是 epoll 的 责 任 。

如 果 多 个 线 程 （ 或 进 程 ， 如 果 子 进 程 通 过 fork (2) 继 承 了 epoll 文 件 描 述 符 ） 等 待 同 一 个 epoll 文 件 描 述 符 ， 且 同 时 在 epoll_wait (2) 中 被 阻 塞 ， 那 么 当 兴 趣 列 表 中 某 个 标 记 为 边 缘 触 发 ( EPOLLET ) 通 知 的 文 件 描 述 符 准 备 就 绪 ， 这 些 线 程 （ 或 进 程 ） 中 只 会 有 一 个 线 程 （ 或 进 程 ） 从 epoll_wait (2) 中 被 唤 醒 。 这 为 避 免 某 些 场 景 下 的 “惊 群 ”（ thundering herd） 唤 醒 提 供 了 有 用 的 优 化 。

系 统 自 动 睡 眠 的 处 理

如 果 系 统 通 过 /sys/power/autosleep 处 于 autosleep 模 式 ， 那 么 当 某 个 事 件 的 发 生 将 设 备 从 睡 眠 中 唤 醒 时 ， 设 备 驱 动 程 序 仅 会 保 持 设 备 唤 醒 直 到 该 事 件 入 队 为 止 。 若 想 保 持 设 备 唤 醒 直 到 事 件 被 处 理 完 毕 ， 则 需 使 用 epoll_ctl (2) 的 EPOLLWAKEUP 标 志 位 。

当 在 struct epoll_event 结 构 体 的 events 段 中 设 置 EPOLLWAKEUP 标 志 位 时 ， 从 事 件 入 队 的 那 一 刻 起 ， 到 epoll_wait (2) 调 用 返 回 事 件 ， 再 一 直 到 下 一 次 epoll_wait (2) 调 用 之 前 ， 系 统 会 一 直 保 持 唤 醒 。 若 要 让 事 件 保 持 系 统 唤 醒 的 时 间 超 过 这 个 时 间 ， 那 么 在 第 二 次 epoll_wait (2) 调 用 之 前 ， 应 当 设 置 一 个 单 独 的 wake_lock 。

/proc 接 口

以 下 接 口 可 以 用 来 限 制 epoll 消 耗 的 内 核 内 存 的 量 。
/proc/sys/fs/epoll/max_user_watches （ 从 Linux 2.6.28 开 始 ）

此 接 口 指 定 了 单 个 用 户 在 系 统 内 所 有 epoll 实 例 中 可 以 注 册 的 文 件 描 述 符 的 总 数 限 制 。 这 个 限 制 是 针 对 每 个 真 实 用 户 ID的 。 每 个 注 册 的 文 件 描 述 符 在 32位 内 核 上 大 约 需 要 90个 字 节 ， 在 64位 内 核 上 大 约 需 要 160个 字 节 。 目 前 ， max_user_watches 的 默 认 值 是 可 用 低 内 存 的 1/25（ 4%） 除 以 注 册 的 空 间 成 本 （ 以 字 节 计 ） 。

示 例 ： 建 议 的 使 用 epoll 的 方 式

epoll 作 为 水 平 触 发 接 口 的 用 法 与 poll (2) 具 有 相 同 的 语 义 ， 但 边 缘 触 发 的 用 法 需 要 更 多 的 说 明 ， 以 避 免 应 用 程 序 事 件 循 环 的 停 滞 。 在 下 面 的 例 子 中 ， 调 用 了 listen (2)来 监 听 listener， 一 个 非 阻 塞 的 套 接 字 。 函 数 do_use_fd() 使 用 新 就 绪 的 文 件 描 述 符 ， 直 到 read (2) 或 write (2) 返 回 EAGAIN 。 一 个 事 件 驱 动 的 状 态 机 应 用 程 序 在 接 收 到 EAGAIN 后 ， 应 该 记 录 它 的 当 前 状 态 ， 这 样 在 下 一 次 调 用 do_use_fd() 时 ， 它 就 能 从 之 前 停 下 的 地 方 继 续 read (2) 或 write (2)。

#define MAX_EVENTS 10
struct epoll_event ev, events[MAX_EVENTS];
int listen_sock, conn_sock, nfds, epollfd;

/* Code to set up listening socket, 'listen_sock',
(socket(), bind(), listen()) omitted. */

epollfd = epoll_create1(0);
if (epollfd == -1) {
perror("epoll_create1");
exit(EXIT_FAILURE);
}

ev.events = EPOLLIN;
ev.data.fd = listen_sock;
if (epoll_ctl(epollfd, EPOLL_CTL_ADD, listen_sock, &ev) == -1) {
perror("epoll_ctl: listen_sock");
exit(EXIT_FAILURE);
}

for (;;) {
nfds = epoll_wait(epollfd, events, MAX_EVENTS, -1);
if (nfds == -1) {
perror("epoll_wait");
exit(EXIT_FAILURE);
}

for (n = 0; n < nfds; ++n) {
if (events[n].data.fd == listen_sock) {
conn_sock = accept(listen_sock,
(struct sockaddr *) &addr, &addrlen);
if (conn_sock == -1) {
perror("accept");
exit(EXIT_FAILURE);
}
setnonblocking(conn_sock);
ev.events = EPOLLIN | EPOLLET;
ev.data.fd = conn_sock;
if (epoll_ctl(epollfd, EPOLL_CTL_ADD, conn_sock,
&ev) == -1) {
perror("epoll_ctl: conn_sock");
exit(EXIT_FAILURE);
}
} else {
do_use_fd(events[n].data.fd);
}
}
}

当 作 为 边 缘 触 发 的 接 口 使 用 时 ， 出 于 性 能 考 虑 ， 可 在 添 加 文 件 描 述 符 （ EPOLL_CTL_ADD ） 时 指 定 ( EPOLLIN | EPOLLOUT )。 这 样 可 以 避 免 反 复 调 用 epoll_ctl (2) 与 EPOLL_CTL_MOD 在 EPOLLIN 和 EPOLLOUT 之 间 来 回 切 换 。

epoll 十 问

0.

用 什 么 区 分 兴 趣 列 表 中 注 册 的 文 件 描 述 符 ？

文 件 描 述 符 的 数 值 和 打 开 文 件 描 述 （ open file description， 又 称 “open file handle”， 内 核 对 打 开 的 文 件 的 内 部 表 示 ） 的 组 合 。

1.

如 果 在 同 一 个 epoll 实 例 上 多 次 注 册 相 同 的 文 件 描 述 符 会 怎 样 ？

你 可 能 会 得 到 EEXIST 。 然 而 ， 在 同 一 个 epoll实 例 上 添 加 重 复 的 （ dup (2), dup2 (2), fcntl (2) F_DUPFD ） 文 件 描 述 符 是 可 能 的 。 如 果 重 复 的 文 件 描 述 符 是 用 不 同 的 事 件 掩 码 （ events mask） 注 册 的 ， 那 么 这 会 成 为 过 滤 事 件 的 一 个 实 用 技 巧 。

2.

多 个 epoll 实 例 能 等 待 同 一 个 文 件 描 述 符 吗 ？ 如 果 可 以 ， 事 件 会 被 报 告 给 所 有 的 这 些 epoll 文 件 描 述 符 吗 ？

能 ， 而 且 事 件 会 被 报 告 给 所 有 的 实 例 。 但 你 可 能 需 要 小 心 仔 细 地 编 程 才 能 正 确 地 实 现 这 一 点 。

3.

epoll 文 件 描 述 符 本 身 poll/epoll/selectable 吗 ？

是 的 ， 如 果 一 个 epoll 文 件 描 述 符 有 事 件 在 等 待 ， 那 么 它 将 显 示 为 可 读 。

4.

如 果 试 图 把 epoll 文 件 描 述 符 放 到 它 自 己 的 文 件 描 述 符 集 合 中 会 发 生 什 么 ？

epoll_ctl (2) 调 用 会 失 败 （ EINVAL ） 。 但 你 可 以 将 一 个 epoll 文 件 描 述 符 添 加 到 另 一 个 epoll 文 件 描 述 符 集 合 中 。

5.

我 可 以 通 过 UNIX 域 套 接 字 发 送 一 个 epoll 文 件 描 述 符 到 另 一 个 进 程 吗 ？

可 以 ， 但 这 样 做 是 没 有 意 义 的 ， 因 为 接 收 进 程 不 会 得 到 兴 趣 列 表 中 文 件 描 述 符 的 副 本 。

6.

关 闭 一 个 文 件 描 述 符 会 将 它 从 所 有 epoll 兴 趣 列 表 中 移 除 吗 ？

会 ， 但 要 注 意 几 点 。 文 件 描 述 符 是 对 打 开 文 件 描 述 （ open file description） 的 引 用 （ 见 open (2)） 。 每 当 通 过 dup (2), dup2 (2), fcntl (2) F_DUPFD ,或 fork (2) 复 制 某 个 文 件 描 述 符 时 ， 都 会 创 建 一 个 新 的 文 件 描 述 符 ， 引 用 同 一 个 打 开 文 件 描 述 。 一 个 打 开 文 件 描 述 会 在 所 有 引 用 它 的 文 件 描 述 符 被 关 闭 之 前 一 直 存 在 。

一 个 文 件 描 述 符 只 有 在 所 有 指 向 其 依 赖 的 打 开 文 件 描 述 的 文 件 描 述 符 都 被 关 闭 后 才 会 从 兴 趣 列 表 中 移 除 。 这 意 味 着 ， 即 使 兴 趣 列 表 内 的 某 个 文 件 描 述 符 被 关 闭 了 ， 如 果 引 用 同 一 文 件 描 述 的 其 他 文 件 描 述 符 仍 然 开 着 ， 则 该 文 件 描 述 符 的 事 件 仍 可 能 会 通 知 。 为 了 防 止 这 种 情 况 发 生 ， 在 复 制 文 件 描 述 符 前 ， 必 须 显 式 地 将 其 从 兴 趣 列 表 中 移 除 （ 使 用 epoll_ctl (2) EPOLL_CTL_DEL ） 。 或 者 应 用 程 序 必 须 能 确 保 所 有 的 文 件 描 述 符 都 被 关 闭 （ 如 果 文 件 描 述 符 是 被 使 用 dup (2) 或 fork (2) 的 库 函 数 隐 式 复 制 的 ,这 一 点 可 能 会 很 难 保 证 ） 。

7.

如 果 在 两 次 epoll_wait (2) 调 用 之 间 发 生 了 不 止 一 个 事 件 ， 它 们 是 会 一 起 报 告 还 是 会 分 开 报 告 ？

它 们 会 一 起 报 告 。

8.

对 文 件 描 述 符 的 操 作 会 影 响 已 经 收 集 到 但 尚 未 报 告 的 事 件 吗 ？

你 可 以 对 某 个 现 有 的 文 件 描 述 符 做 删 除 和 修 改 两 种 操 作 ： 删 除 ， 对 这 种 情 况 没 有 意 义 ； 修 改 ， 将 重 新 读 取 可 用 的 I/O。

9.

当 使 用 EPOLLET 标 志 位 （ 边 缘 触 发 行 为 ） 时 ， 我 需 要 持 续 读 /写 文 件 描 述 符 ， 直 到 EAGAIN 吗 ？

从 epoll_wait (2) 收 到 的 事 件 会 提 示 你 ， 对 应 的 文 件 描 述 符 已 经 准 备 好 进 行 所 要 求 的 I/O 操 作 。 直 到 下 一 次 （ 非 阻 塞 的 ） 读 /写 产 生 EAGAIN 之 前 ， 此 文 件 描 述 符 都 应 被 认 为 是 就 绪 的 。 何 时 及 如 何 使 用 该 文 件 描 述 符 完 全 取 决 于 你 。

对 于 面 向 数 据 包 /令 牌 的 文 件 （ 如 数 据 报 套 接 字 、 典 型 模 式 （ canonical mode） 下 的 终 端 ） ,感 知 读 /写 I/O 空 间 尽 头 的 唯 一 方 法 是 持 续 读 /写 直 到 EAGAIN 。

对 于 面 向 流 的 文 件 （ 如 管 道 、 FIFO、 流 套 接 字 ） ， 也 可 通 过 检 查 从 目 标 文 件 描 述 符 读 /写 的 数 据 量 来 检 测 读 /写 I/O 空 间 消 费 完 的 情 况 。 例 如 ， 如 果 你 在 调 用 read (2) 时 指 定 了 期 望 读 取 的 字 节 数 ， 但 read (2) 返 回 的 实 际 读 取 字 节 数 较 少 ， 你 就 可 以 确 定 文 件 描 述 符 的 读 I/O 空 间 已 经 消 费 完 了 。 在 使 用 write (2) 写 入 时 同 理 。 （ 但 如 果 你 不 能 保 证 被 监 视 的 文 件 描 述 符 总 是 指 向 一 个 面 向 流 的 文 件 ， 那 么 就 应 当 避 免 使 用 这 一 技 巧 ）

可 能 的 陷 阱 和 避 免 的 方 法

o 边 缘 触 发 下 的 饥 饿

如 果 某 个 就 绪 的 文 件 可 用 的 I/O 空 间 很 大 ， 试 图 穷 尽 它 可 能 会 导 致 其 他 文 件 得 不 到 处 理 ， 造 成 饥 饿 。 (但 这 个 问 题 并 不 是 epoll 特 有 的 ） 。

解 决 方 案 是 维 护 一 个 就 绪 列 表 ， 并 在 其 关 联 的 数 据 结 构 中 将 此 文 件 描 述 符 标 记 为 就 绪 ， 从 而 使 应 用 程 序 在 记 住 哪 些 文 件 需 要 被 处 理 的 同 时 仍 能 循 环 遍 历 所 有 就 绪 的 文 件 。 这 也 使 你 可 以 忽 略 收 到 的 已 经 就 绪 的 文 件 描 述 符 的 后 续 事 件 。
o 如 果 使 用 了 事 件 缓 存 ...

如 果 你 使 用 了 事 件 缓 存 或 暂 存 了 所 有 从 epoll_wait (2) 返 回 的 文 件 描 述 符 ， 那 么 一 定 要 有 某 种 方 法 来 动 态 地 标 记 这 些 文 件 描 述 符 的 关 闭 （ 例 如 因 先 前 的 事 件 处 理 引 起 的 文 件 描 述 符 关 闭 ） 。 假 设 你 从 epoll_wait (2) 收 到 了 100个 事 件 ， 在 事 件 #47中 ， 某 个 条 件 导 致 事 件 #13被 关 闭 。 如 果 你 删 除 数 据 结 构 并 关 闭 （ close (2)） 事 件 #13的 文 件 描 述 符 ， 那 么 你 的 事 件 缓 存 可 能 仍 然 会 说 事 件 #13的 文 件 描 述 符 有 事 件 在 等 待 而 造 成 迷 惑 。

对 应 的 一 个 解 决 方 案 是 ， 在 处 理 事 件 47的 过 程 中 ， 调 用 epoll_ctl ( EPOLL_CTL_DEL )来 删 除 并 关 闭 （ close (2)） 文 件 描 述 符 13， 然 后 将 其 相 关 的 数 据 结 构 标 记 为 已 删 除 ， 并 将 其 链 接 到 一 个 清 理 列 表 。 如 果 你 在 批 处 理 中 发 现 了 文 件 描 述 符 13的 另 一 个 事 件 ， 你 会 发 现 文 件 描 述 符 13先 前 已 被 删 除 ， 这 样 就 不 会 有 任 何 混 淆 。

版 本

epoll API 在 Linux 内 核 2.5.44中 引 入 。 2.3.2版 本 的 glibc 加 入 了 对 其 的 支 持 。

适 用 于

epoll API 是 Linux 特 有 的 。 其 他 的 一 些 系 统 也 提 供 类 似 的 机 制 ， 例 如 FreeBSD有 kqueue ， Solaris 有 /dev/poll 。

注

可 以 通 过 进 程 对 应 的 /proc/[pid]/fdinfo 目 录 下 的 epoll 文 件 描 述 符 条 目 查 看 epoll 文 件 描 述 符 所 监 视 的 文 件 描 述 符 的 集 合 。 详 情 见 proc (5)。

kcmp (2) 的 KCMP_EPOLL_TFD 操 作 可 以 用 来 检 查 一 个 epoll 实 例 中 是 否 存 在 某 个 文 件 描 述 符 。

另 请 参 阅

epoll_create (2), epoll_create1 (2), epoll_ctl (2), epoll_wait (2), poll (2), select (2)

跋

本 页 面 中 文 版 由 中 文 man 手 册 页 计 划 提 供 。
中 文 man 手 册 页 计 划 ： https://github.com/man-pages-zh/manpages-zh