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