Provided by: manpages-ja_0.5.0.0.20140515+dfsg-2_all 
名前
epoll - I/O イベント通知機能
書式
#include <sys/epoll.h>
説明
epoll API は poll(2) と同様の処理を行う、つまり、複数のファイルディスク リプタを監視し、その中のいずれか
が入出力可能な状態であるかを確認する。 epoll API は、エッジトリガインタフェースとレベルトリガインタフェー
スの いずれとしても使用することができ、監視するファイルディスクリプタの数が多い 場合にも使用できる。
epoll インスタンスの作成や管理を行うために 以下のシステムコールが提供されている:
* epoll_create(2) は epoll インスタンスを作成し、そのインスタンスを参照する ファイルディスクリプタを返
す。(もっと新しい epoll_create1(2) では、 epoll_create(2) の機能が拡張されている)。
* 特定のファイルディスクリプタに対する監視内容を epoll_ctl(2) で登録する。 epoll インスタンスに現在登録
されているファイルディスクリプタの集合は epoll 集合と呼ばれることもある。
* epoll_wait(2) は I/O イベントを待つ。 現在利用可能な状態のイベントがなければ、呼び出したスレッドを停止
する。
レベルトリガとエッジトリガ
epoll イベント配送 (distribution) インタフェースは、 エッジトリガ (ET) としてもレベルトリガ (LT) としても
動作させることができる。 二つの配送機構の違いは、次のように説明できる。 このようなシナリオが起こったとし
よう:
1. パイプの読み込み側を表すファイルディスクリプタ (rfd) が epoll インスタンスに登録される。
2. パイプへ書き込むプログラムが 2 kB のデータをパイプの書き込み側へ書き込む。
3. epoll_wait(2) を呼び出すと、読み込み可能 (ready) なファイルディスクリプタとして rfd が返る。
4. パイプから読み出すプログラムが、1 kB のデータを rfd から読み出す。
5. epoll_wait(2) の呼び出しが行われる。
rfd ファイルディスクリプタが EPOLLET フラグ (エッジトリガ) を使って epoll に追加されていると、 利用可能な
データがファイル入力バッファにまだ存在するにもかかわらず ステップ 5 の epoll_wait(2) の呼び出しでハングす
る可能性がある。 その一方で、リモートの接続先 (peer) は既に送られたデータに 基づいて応答を期待しているか
もしれない。 このようなことが起こる理由は、エッジトリガイベント配送では、 モニタしているファイルでイベン
トが起ったときにのみイベントが 配送されるためである。 したがって、ステップ 5 では、呼び出し側は結果的に
入力バッファ内にすで存在するデータを待つことになるかもしれない。 上記の例では、 2 で行われた書き込みに
よって rfd に関するイベントが生成され、 3 でイベントが消費 (consume) される。 4 で行われる読み込み操作で
は、全部のバッファデータを消費しないので、 ステップ 5 で行われる epoll_wait(2) の呼び出しが 無期限に停止
(block) するかもしれない。
EPOLLET フラグを採用するアプリケーションでは、 インタフェースはブロックしない (nonblocking) ファイルディ
スクリプタを 使うべきである。 これは、ブロックされる読み込みや書き込みによって、 複数のファイルディスクリ
プタを扱うタスクが 停止してしまうのを避けるためである。 epoll をエッジトリガ (EPOLLET) インタフェースと
して使うために提案される方法は以下の通りである。
i ブロックしないファイルディスクリプタと共に使う。
ii read(2) または write(2) が EAGAIN を返した後でのみ、イベントを待つ。
一方、レベルトリガインタフェースとして使う場合
(こちらがデフォルトである、 EPOLLET が指定されなかった場合)、 epoll は単に高速な poll(2) であり、使い方
が同じなので、 poll(2) が使われているところではどこでも使用することができる。
エッジトリガを使った場合でも、複数のデータを受信すると複数の epoll イベントが生成されるので、 呼び出し側
には EPOLLONESHOT フラグを指定するオプションがある。 このフラグは epoll に対して、 epoll_wait(2) によるイ
ベントを受信した後で、関連するファイルディスクリプタを無効にさせる。 EPOLLONESHOT フラグが指定された場
合、 epoll_ctl(2) に EPOLL_CTL_MOD を指定してファイルディスクリプタを再度使用できるようにするのは、 呼び
出し側の責任である。
/proc インタフェース
epoll が消費するカーネルメモリの量を制限するために、 以下のインタフェースを使用することができる。
/proc/sys/fs/epoll/max_user_watches (Linux 2.6.28 以降)
このファイルは、あるユーザがシステム上の全ての epoll インスタンスに 登録できるファイルディスクリプ
タの総数の上限を規定する。 この上限は実ユーザ ID 単位である。 登録されたファイルディスクリプタ 1
つが消費するメモリ量は、 32 ビットカーネルでおよそ 90 バイト、 64 ビットカーネルでおよそ 160 バイ
トである。 現在のところ、 max_user_watches のデフォルト値は、利用可能なメモリ下限の 1/25 (4%) であ
り、 登録で消費されるメモリ量 (バイト単位) で割った値となる。
おすすめな使用例
レベルトリガインタフェースとして使用するときの epoll の使い方は poll(2) と同じである。 しかしエッジトリ
ガとして使う場合は、 アプリケーションのイベントループでストール (stall) しないように、 使い方をより明確に
しておく必要がある。 この例では、リスナはブロックしないソケットであり、 listen(2) が呼ばれている。 関数
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;
/* Set up listening socket, 'listen_sock' (socket(),
bind(), listen()) */
epollfd = epoll_create(10);
if (epollfd == -1) {
perror("epoll_create");
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_pwait");
exit(EXIT_FAILURE);
}
for (n = 0; n < nfds; ++n) {
if (events[n].data.fd == listen_sock) {
conn_sock = accept(listen_sock,
(struct sockaddr *) &local, &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);
}
}
}
エッジトリガインタフェースとして使う場合、性能上の理由により、 一度 (EPOLLIN|EPOLLOUT) を指定してから
(EPOLL_CTL_ADD で) ファイルディスクリプタを epoll インタフェースに追加することができる。 これにより、
epoll_ctl(2) に EPOLL_CTL_MOD を指定して呼び出すことで EPOLLIN と EPOLLOUT の連続的な切り替えが避けられ
る。
質問と解答
Q0 epoll 集合内の登録されたファイルディスクリプタを区別するには、 何をキーとして使えばよいか？
A0 キーはファイルディスクリプタ番号とオープンファイル記述 (open file description) の組である (オープン
ファイル記述は "open file handle" とも 呼ばれ、オープンされたファイルのカーネルの内部表現である)。
Q1 1 つの epoll インスタンスに同じファイルディスクリプタを 2 回登録するとどうなるか？
A1 たぶん EEXIST を受け取るだろう。 しかしながら、同じ epoll インスタンスに対して複製されたディスクリプ
タを追加することは可能である (dup(2), dup2(2), fcntl(2) F_DUPFD など)。 複製したファイルディスクリプ
タを異なる events マスクで登録すれば、イベントをフィルタリングするのに この機能は有用な手法である。
Q2 2 つの epoll インスタンスが同じファイルディスクリプタを待ち受けることは可能か？ もし可能であれば、イ
ベントは両方の epoll ファイルディスクリプタに報告されるか？
A2 イベントは両方に報告される。 しかしながら、これを正しく扱うには注意深くプログラミングする必要が ある
かもしれない。
Q3 epoll ファイルディスクリプタ自身は poll/epoll/select が可能か？
A3 可能である。 epoll ファイルディスクリプタに処理待ちのイベントがある場合は、 読み出し可能だと通知され
ることだろう。
Q4 epoll ファイルディスクリプタを自身のファイルディスクリプタ集合に 入れようとするとどうなるか？
A4 epoll_ctl(2) の呼び出しは (EINVAL で) 失敗するだろう。 ただし epoll ファイルディスクリプタを他の
epoll ファイルディスクリプタ集合の内部に追加することは可能である。
Q5 epoll ファイルディスクリプタを UNIX ドメインソケットで他のプロセスに送ることは可能か？
A5 可能だが、これをすることに意味はない。 なぜなら、受信側のプロセスが epoll 集合内のファイルディスクリ
プタのコピーを持っていないからである。
Q6 ファイルディスクリプタをクローズすると、そのファイルディスクリプタは全ての epoll 集合から自動的に削除
されるか？
A6 削除されるが、以下の点に注意が必要である。 ファイルディスクリプタはオープンファイル記述 (open(2) 参
照) への参照である。 ディスクリプタの複製を dup(2), dup2(2), fcntl(2) の F_DUPFD や fork(2) 経由で行
う度に、同じオープンファイル記述を参照する新規のファイル ディスクリプタが生成される。 オープンファイ
ル記述自体は、自身を参照する全てのファイルディスクリプタ がクローズされるまで存在し続ける。 ファイル
ディスクリプタが epoll 集合から削除されるのは、対応するオープンファイル記述を参照している 全てのファ
イルディスクリプタがクローズされた後である (epoll_ctl(2) EPOLL_CTL_DEL を使ってそのディスクリプタを
明示的に削除した場合にも削除される)。 このことは、 epoll 集合に属しているあるファイルディスクリプタを
クローズした後であっても、 同じファイル記述を参照する他のファイルディスクリプタがオープンされている間
は、 クローズしたファイルディスクリプタ宛にイベントが報告される可能性があると いうことを意味する。
Q7 2 つ以上のイベントが epoll_wait(2) コールの間に発生した場合、それらはまとめて報告されるか、 それとも
別々に報告されるか？
A7 まとめて報告されるだろう。
Q8 ファイルディスクリプタに対する操作は、 既に集められているがまだ報告されていないイベントに影響するか？
A8 既存のファイルディスクリプタに対して 2 つの操作を行うことができる。 この場合、削除には意味がない。 変
更すると、使用可能な I/O が再び読み込まれる。
Q9 EPOLLET フラグ (エッジトリガ動作) を使っている場合、 EAGAIN を受け取るまで、 継続してファイルディスク
リプタを読み書きする必要があるか？
A9 epoll_wait(2) からイベントを受け取ることは、 そのファイルディスクリプタが要求された I/O 操作に対して
準備済みである、 ということをユーザに示すものである。 次の (ブロックしない) read/write で EAGAIN を受
け取るまではファイルディスクリプタは準備済みであると 考えなければならない。 そのファイルディスクリプ
タをいつどのように使うかは、 全くユーザに任されてる。
パケット指向やトークン指向のファイル (例えば、データグラムソケット、 canonical モードの端末) では、
読み込み用 / 書き込み用の I/O 空間の末尾を検知する唯一の方法は EAGAIN になるまで read/write を行うこ
とである。
ストリーム指向のファイル (例えば、パイプ、FIFO、ストリームソケット) では、 読み込み用 / 書き込み用の
I/O 空間が使い尽くされた状態は、 対象となるファイルディスクリプタから読み込んだデータ量または 書き込
んだデータ量をチェックすることでも検知できる。 例えば、ある特定の量のデータを読み込むために read(2)
を呼んだときに、 read(2) が返したバイト数がそれより少なかった場合、 そのファイルディスクリプタの読み
込み用 I/O 空間が 使い尽くされたことが分かる。 write(2) を使って書き込みをするときも、同じことが言え
る (監視しているファイルディスクリプタが常にストリーム指向のファイルを 参照していることを保証できない
場合には、後者の手法の使用を避けること)。
ありがちな落とし穴と回避方法
o 飢餓 (starvation) (エッジトリガ)
大きな I/O 空間がある場合、 その I/O 空間のデータを全て処理 (drain) しようとすると、 他のファイルが処理さ
れず、飢餓を発生させることがある (この問題は epoll に固有のものではない)。
この問題の解決法は、準備済み状態のリストを管理して、 関連する data 構造体の中でファイルディスクリプタが
利用可能であるとマークすることである。 それによって、利用可能なすべてのファイルの中で どのファイルを処理
する必要があるかを憶えることができ、 しかも順番に処理 (round robin) することができる。 既に利用可能である
ファイルディスクリプタに対して それ以後に受け取るイベントを無視することもできる。
o イベントキャッシュを使っている場合
イベントキャッシュを使っている場合、 または epoll_wait(2) から返された全てのファイルディスクリプタを格納
している場合、 クローズされたことを動的にマークする (つまり前のイベントの処理によってマークされる) 方法を
提供すべきである。 epoll_wait(2) から 100 個のイベントを受け取り、 イベント #47 ではある条件でイベント
#13 が閉じられると仮定する。 イベント #13 の構造体を削除しファイルディスクリプタを close(2) すると、イベ
ントキャッシュはそのファイルディスクリプタを待つイベントが 存在するといって、混乱が起きる。
この問題を解決する 1 つの方法は、イベント 47 の処理をしている間に、 ファイルディスクリプタ 13 を削除して
close(2) するために epoll_ctl(EPOLL_CTL_DEL) を呼び出し、関連付けられた data 構造体を削除済みとマークし
て、 クリーンアップリストにリンクすることである。 バッチ処理の中でファイルディスクリプタ 13 についての 他
のイベントを見つけた場合、 そのファイルディスクリプタが以前に削除されたものであると分かるので、 混乱は起
きない。
バージョン
epoll API は Linux カーネル 2.5.44 に導入された。 glibc でのサポートはバージョン 2.3.2 で追加された。
準拠
epoll API は Linux 固有である。 他のシステムでも同様の機構が提供されている場合がある。 例えば、FreeBSD の
kqueue や Solaris の /dev/poll などである。
関連項目
epoll_create(2), epoll_create1(2), epoll_ctl(2), epoll_wait(2)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 3.65 の一部 である。プロジェクトの説明とバグ報告
に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。