manual/LDP_man-pages/release/man7/epoll.7

   1 .\"
   2 .\"  epoll by Davide Libenzi ( efficient event notification retrieval )
   3 .\"  Copyright (C) 2003  Davide Libenzi
   4 .\"
   5 .\"  This program is free software; you can redistribute it and/or modify
   6 .\"  it under the terms of the GNU General Public License as published by
   7 .\"  the Free Software Foundation; either version 2 of the License, or
   8 .\"  (at your option) any later version.
   9 .\"
  10 .\"  This program is distributed in the hope that it will be useful,
  11 .\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 .\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 .\"  GNU General Public License for more details.
  14 .\"
  15 .\"  You should have received a copy of the GNU General Public License
  16 .\"  along with this program; if not, write to the Free Software
  17 .\"  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18 .\"
  19 .\"  Davide Libenzi <davidel@xmailserver.org>
  20 .\"
  21 .\" Japanese Version Copyright (c) 2004-2005 Yuichi SATO
  22 .\"         all rights reserved.
  23 .\" Translated Sat Jun 19 07:50:04 JST 2004
  24 .\"         by Yuichi SATO <ysato444@yahoo.co.jp>
  25 .\" Updated & Modified 2005-01-18, Yuichi SATO
  26 .\" Updated 2006-07-14, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  27 .\"         Catch up to LDP v2.34. epoll.4 is renamed to epoll.7.
  28 .\" Updated 2007-09-07, Akihiro MOTOKI, LDP v2.64
  29 .\" Updated 2008-04-08, Akihiro MOTOKI, LDP v2.79
  30 .\" Updated 2009-02-23, Akihiro MOTOKI, LDP v3.19
  31 .\"
  32 .TH EPOLL 7 2009-02-01 "Linux" "Linux Programmer's Manual"
  33 .SH 名前
  34 epoll \- I/O イベント通知機能
  35 .SH 書式
  36 .B #include <sys/epoll.h>
  37 .SH 説明
  38 .B epoll
  39 は
  40 .BR poll (2)
  41 の一種であり、エッジトリガインタフェースと
  42 レベルトリガインタフェースのどちらとしても使用することができ、
  43 監視するファイルディスクリプタの数が多い場合にも使用できる。
  44 .B epoll
  45 インスタンスの作成や管理を行うために
  46 以下のシステムコールが提供されている:
  47 .IP * 3
  48 .B epoll
  49 インスタンスは
  50 .BR epoll_create (2)
  51 で作成される。
  52 .BR epoll_create (2)
  53 は作成した epoll インスタンスを参照するファイルディスクリプタを返す。
  54 (もっと新しい
  55 .BR epoll_create1 (2)
  56 では、
  57 .BR epoll_create (2)
  58 の機能が拡張されている)。
  59 .IP *
  60 特定のファイルディスクリプタに対する監視内容を
  61 .BR epoll_ctl (2)
  62 で登録する。
  63 .B epoll
  64 インスタンスに現在登録されているファイルディスクリプタの集合は
  65 .I epoll
  66 集合と呼ばれることもある。
  67 .IP *
  68 最後に
  69 .BR epoll_wait (2)
  70 で実際のイベント待ちを開始する。
  71 .SS レベルトリガとエッジトリガ
  72 .B epoll
  73 イベント配送 (distribution) インタフェースは、
  74 エッジトリガ (ET) としてもレベルトリガ (LT) としても動作させることができる。
  75 二つの配送機構の違いは、次のように説明できる。
  76 このようなシナリオが起こったとしよう:
  77 .IP 1. 3
  78 パイプの読み込み側を表すファイルディスクリプタ
  79 .RI ( rfd )
  80 が
  81 .B epoll
  82 インスタンスに登録される。
  83 .IP 2.
  84 パイプへ書き込むプログラムが 2 kB のデータをパイプの書き込み側へ書き込む。
  85 .IP 3.
  86 .BR epoll_wait (2)
  87 を呼び出すと、読み込み可能 (ready) なファイルディスクリプタとして
  88 .I rfd
  89 が返る。
  90 .IP 4.
  91 パイプから読み出すプログラムが、1 kB のデータを
  92 .I rfd
  93 から読み出す。
  94 .IP 5.
  95 .BR epoll_wait (2)
  96 の呼び出しが行われる。
  97 .PP
  98 .I rfd
  99 ファイルディスクリプタが
 100 .B EPOLLET
 101 フラグ (エッジトリガ) を使って
 102 .B epoll
 103 に追加されていると、
 104 利用可能なデータがファイル入力バッファにまだ存在するにもかかわらず
 105 ステップ
 106 .B 5
 107 の
 108 .BR epoll_wait (2)
 109 の呼び出しでハングする可能性がある。
 110 その一方で、リモートの接続先 (peer) は既に送られたデータに
 111 基づいて応答を期待しているかもしれない。
 112 このようなことが起こる理由は、エッジトリガイベント配送では、
 113 モニタしているファイルでイベントが起ったときにのみイベントが
 114 配送されるためである。
 115 したがって、ステップ
 116 .B 5
 117 では、呼び出し側は結果的に
 118 入力バッファ内にすで存在するデータを待つことになるかもしれない。
 119 上記の例では、
 120 .B 2
 121 で行われた書き込みによって
 122 .I rfd
 123 に関するイベントが生成され、
 124 .B 3
 125 でイベントが消費 (consume) される。
 126 .B 4
 127 で行われる読み込み操作では、全部のバッファデータを消費しないので、
 128 ステップ
 129 .B 5
 130 で行われる
 131 .BR epoll_wait (2)
 132 の呼び出しが
 133 無期限に停止 (block) するかもしれない。
 134
 135 .B EPOLLET
 136 フラグを採用するアプリケーションでは、
 137 インタフェースはブロックしない (nonblocking) ファイルディスクリプタを
 138 使うべきである。
 139 これは、ブロックされる読み込みや書き込みによって、
 140 複数のファイルディスクリプタを扱うタスクが
 141 停止してしまうのを避けるためである。
 142 .B epoll
 143 をエッジトリガ
 144 .RB ( EPOLLET )
 145 インタフェースとして使うために提案される方法は以下の通りである。
 146 .RS
 147 .TP 4
 148 .B i
 149 ブロックしないファイルディスクリプタと共に使う。
 150 .TP
 151 .B ii
 152 .BR read (2)
 153 または
 154 .BR write (2)
 155 が
 156 .B EAGAIN
 157 を返した後でのみ、イベントを待つ。
 158 .RE
 159 .PP
 160 一方、レベルトリガインタフェースとして使う場合
 161  (こちらがデフォルトである、
 162 .B EPOLLET
 163 が指定されなかった場合)、
 164 .B epoll
 165 は単に高速な
 166 .BR poll (2)
 167 であり、使い方が同じなので、
 168 .BR poll (2)
 169 が使われているところではどこでも使用することができる。
 170
 171 エッジトリガを使った場合でも、複数のデータを受信すると複数の
 172 .B epoll
 173 イベントが生成されるので、
 174 呼び出し側には
 175 .B EPOLLONESHOT
 176 フラグを指定するオプションがある。
 177 このフラグは
 178 .B epoll
 179 に対して、
 180 .BR epoll_wait (2)
 181 によるイベントを受信した後で、関連するファイルディスクリプタを無効にさせる。
 182 .B EPOLLONESHOT
 183 フラグが指定された場合、
 184 .BR epoll_ctl (2)
 185 に
 186 .B EPOLL_CTL_MOD
 187 を指定してファイルディスクリプタを再度使用できるようにするのは、
 188 呼び出し側の責任である。
 189 .SS /proc インタフェース
 190 epoll が消費するカーネルメモリの量を制限するために、
 191 以下のインタフェースを使用することができる。
 192 .TP
 193 .\" Following was added in 2.6.28, but them removed in 2.6.29
 194 .\" .TP
 195 .\" .IR /proc/sys/fs/epoll/max_user_instances " (since Linux 2.6.28)"
 196 .\" This specifies an upper limit on the number of epoll instances
 197 .\" that can be created per real user ID.
 198 .TP
 199 .IR /proc/sys/fs/epoll/max_user_watches " (Linux 2.6.28 以降)"
 200 このファイルは、あるユーザがシステム上の全ての epoll インスタンスに
 201 登録できるファイルディスクリプタの総数の上限を規定する。
 202 この上限は実ユーザ ID 単位である。
 203 登録されたファイルディスクリプタ 1 つが消費するメモリ量は、
 204 32 ビットカーネルでおよそ 90 バイト、
 205 64 ビットカーネルでおよそ 160 バイトである。
 206 .\" 2.6.29 (in 2.6.28, the default was 1/32 of lowmem)
 207 現在のところ、
 208 .I max_user_watches
 209 のデフォルト値は、利用可能なメモリ下限の 1/25 (4%) であり、
 210 登録で消費されるメモリ量 (バイト単位) で割った値となる。
 211 .SS おすすめな使用例
 212 レベルトリガインタフェースとして使用するときの
 213 .B epoll
 214 の使い方は
 215 .BR poll (2)
 216 と同じである。
 217 しかしエッジトリガとして使う場合は、
 218 アプリケーションのイベントループでストール (stall) しないように、
 219 使い方をより明確にしておく必要がある。
 220 この例では、リスナはブロックしないソケットであり、
 221 .BR listen (2)
 222 が呼ばれている。
 223 関数
 224 .I do_use_fd()
 225 は、
 226 .BR read (2)
 227 または
 228 .BR write (2)
 229 によって
 230 .B EAGAIN
 231 が返されるまでは、新しい準備済みのファイルディスクリプタを使う。
 232 イベント駆動ステートマシンアプリケーションは、
 233 .B EAGAIN
 234 を受信した後、カレントの状態を記録しておくべきである。
 235 これにより、次の
 236 .I do_use_fd()
 237 呼び出しのときに、以前に停止したところから
 238 .BR read (2)
 239 または
 240 .BR write (2)
 241 を継続することができる。
 242
 243 .in +4n
 244 .nf
 245 #define MAX_EVENTS 10
 246 struct epoll_event ev, events[MAX_EVENTS];
 247 int listen_sock, conn_sock, nfds, epollfd;
 248
 249 /* Set up listening socket, \(aqlisten_sock\(aq (socket(),
 250    bind(), listen()) */
 251
 252 epollfd = epoll_create(10);
 253 if (epollfd == \-1) {
 254     perror("epoll_create");
 255     exit(EXIT_FAILURE);
 256 }
 257
 258 ev.events = EPOLLIN;
 259 ev.data.fd = listen_sock;
 260 if (epoll_ctl(epollfd, EPOLL_CTL_ADD, listen_sock, &ev) == \-1) {
 261     perror("epoll_ctl: listen_sock");
 262     exit(EXIT_FAILURE);
 263 }
 264
 265 for (;;) {
 266     nfds = epoll_wait(epollfd, events, MAX_EVENTS, \-1);
 267     if (nfds == \-1) {
 268         perror("epoll_pwait");
 269         exit(EXIT_FAILURE);
 270     }
 271
 272     for (n = 0; n < nfds; ++n) {
 273         if (events[n].data.fd == listen_sock) {
 274             conn_sock = accept(listen_sock,
 275                             (struct sockaddr *) &local, &addrlen);
 276             if (conn_sock == \-1) {
 277                 perror("accept");
 278                 exit(EXIT_FAILURE);
 279             }
 280             setnonblocking(conn_sock);
 281             ev.events = EPOLLIN | EPOLLET;
 282             ev.data.fd = conn_sock;
 283             if (epoll_ctl(epollfd, EPOLL_CTL_ADD, conn_sock,
 284                         &ev) == \-1) {
 285                 perror("epoll_ctl: conn_sock");
 286                 exit(EXIT_FAILURE);
 287             }
 288         } else {
 289             do_use_fd(events[n].data.fd);
 290         }
 291     }
 292 }
 293 .fi
 294 .in
 295
 296 エッジトリガインタフェースとして使う場合、性能上の理由により、
 297 一度
 298 .RB ( EPOLLIN | EPOLLOUT )
 299 を指定してから
 300 .RB ( EPOLL_CTL_ADD
 301 で) ファイルディスクリプタを
 302 .B epoll
 303 インタフェースに追加することができる。
 304 これにより、
 305 .BR epoll_ctl (2)
 306 に
 307 .B EPOLL_CTL_MOD
 308 を指定して呼び出すことで
 309 .B EPOLLIN
 310 と
 311 .B EPOLLOUT
 312 の連続的な切り替えが避けられる。
 313 .SS 質問と解答
 314 .TP 4
 315 .B Q0
 316 .B epoll
 317 集合内の登録されたファイルディスクリプタを区別するには、
 318 何をキーとして使えばよいか？
 319 .TP
 320 .B A0
 321 キーはファイルディスクリプタ番号とオープンファイル記述 (open file
 322 description) の組である (オープンファイル記述は "open file handle" とも
 323 呼ばれ、オープンされたファイルのカーネルの内部表現である)。
 324 .TP
 325 .B Q1
 326 1 つの
 327 .B epoll
 328 インスタンスに同じファイルディスクリプタを 2 回登録するとどうなるか？
 329 .TP
 330 .B A1
 331 たぶん
 332 .B EEXIST
 333 を受け取るだろう。
 334 しかしながら、同じ
 335 .B epoll
 336 インスタンスに対して複製されたディスクリプタを追加することは可能である
 337 .RB ( dup (2),
 338 .BR dup2 (2),
 339 .BR fcntl (2)
 340 .B F_DUPFD
 341 など)。
 342 .\" But a descriptor duplicated by fork(2) can't be added to the
 343 .\" set, because the [file *, fd] pair is already in the epoll set.
 344 .\" That is a somewhat ugly inconsistency.  On the one hand, a child process
 345 .\" cannot add the duplicate file descriptor to the epoll set.  (In every
 346 .\" other case that I can think of, descriptors duplicated by fork have
 347 .\" similar semantics to descriptors duplicated by dup() and friends.)  On
 348 .\" the other hand, the very fact that the child has a duplicate of the
 349 .\" descriptor means that even if the parent closes its descriptor, then
 350 .\" epoll_wait() in the parent will continue to receive notifications for
 351 .\" that descriptor because of the duplicated descriptor in the child.
 352 .\"
 353 .\" See http://thread.gmane.org/gmane.linux.kernel/596462/
 354 .\" "epoll design problems with common fork/exec patterns"
 355 .\"
 356 .\" mtk, Feb 2008
 357 複製したファイルディスクリプタを異なる
 358 .I events
 359 マスクで登録すれば、イベントをフィルタリングするのに
 360 この機能は有用な手法である。
 361 .TP
 362 .B Q2
 363 2 つの
 364 .B epoll
 365 インスタンスが同じファイルディスクリプタを待ち受けることは可能か？
 366 もし可能であれば、イベントは両方の
 367 .B epoll
 368 ファイルディスクリプタに報告されるか？
 369 .TP
 370 .B A2
 371 イベントは両方に報告される。
 372 しかしながら、これを正しく扱うには注意深くプログラミングする必要が
 373 あるかもしれない。
 374 .TP
 375 .B Q3
 376 .B epoll
 377 ファイルディスクリプタ自身は poll/epoll/select が可能か？
 378 .TP
 379 .B A3
 380 可能である。
 381 .B epoll
 382 ファイルディスクリプタに処理待ちのイベントがある場合は、
 383 読み出し可能だと通知されることだろう。
 384 .TP
 385 .B Q4
 386 .B epoll
 387 ファイルディスクリプタを自身のファイルディスクリプタ集合に
 388 入れようとするとどうなるか？
 389 .TP
 390 .B A4
 391 .BR epoll_ctl (2)
 392 の呼び出しは
 393 .RB ( EINVAL
 394 で) 失敗するだろう。
 395 ただし
 396 .B epoll
 397 ファイルディスクリプタを他の
 398 .B epoll
 399 ファイルディスクリプタ集合の内部に追加することは可能である。
 400 .TP
 401 .B Q5
 402 .B epoll
 403 ファイルディスクリプタを UNIX ドメインソケットで他のプロセスに送ることは可能か？
 404 .TP
 405 .B A5
 406 可能だが、これをすることに意味はない。
 407 なぜなら、受信側のプロセスが
 408 .B epoll
 409 集合内のファイルディスクリプタのコピーを持っていないからである。
 410 .TP
 411 .B Q6
 412 ファイルディスクリプタをクローズすると、そのファイルディスクリプタは全ての
 413 .B epoll
 414 集合から自動的に削除されるか？
 415 .TP
 416 .B A6
 417 削除されるが、以下の点に注意が必要である。
 418 ファイルディスクリプタはオープンファイル記述
 419 .RB ( open (2)
 420 参照) への参照である。
 421 ディスクリプタの複製を
 422 .BR dup (2),
 423 .BR dup2 (2),
 424 .BR fcntl (2)
 425 の
 426 .B F_DUPFD
 427 や
 428 .BR fork (2)
 429 経由で行う度に、同じオープンファイル記述を参照する新規のファイル
 430 ディスクリプタが生成される。
 431 オープンファイル記述自体は、自身を参照する全てのファイルディスクリプタ
 432 がクローズされるまで存在し続ける。
 433 ファイルディスクリプタが
 434 .B epoll
 435 集合から削除されるのは、対応するオープンファイル記述を参照している
 436 全てのファイルディスクリプタがクローズされた後である
 437 .RB ( epoll_ctl (2)
 438 .B EPOLL_CTL_DEL
 439 を使ってそのディスクリプタを明示的に削除した場合にも削除される)。
 440 このことは、
 441 .B epoll
 442 集合に属しているあるファイルディスクリプタをクローズした後であっても、
 443 同じファイル記述を参照する他のファイルディスクリプタがオープンされている間は、
 444 クローズしたファイルディスクリプタ宛にイベントが報告される可能性があると
 445 いうことを意味する。
 446 .TP
 447 .B Q7
 448 2 つ以上のイベントが
 449 .BR epoll_wait (2)
 450 コールの間に発生した場合、それらはまとめて報告されるか、
 451 それとも別々に報告されるか？
 452 .TP
 453 .B A7
 454 まとめて報告されるだろう。
 455 .TP
 456 .B Q8
 457 ファイルディスクリプタに対する操作は、
 458 既に集められているがまだ報告されていないイベントに影響するか？
 459 .TP
 460 .B A8
 461 既存のファイルディスクリプタに対して 2 つの操作を行うことができる。
 462 この場合、削除には意味がない。
 463 変更すると、使用可能な I/O が再び読み込まれる。
 464 .TP
 465 .B Q9
 466 .B EPOLLET
 467 フラグ (エッジトリガ動作) を使っている場合、
 468 .B EAGAIN
 469 を受け取るまで、
 470 継続してファイルディスクリプタを読み書きする必要があるか？
 471 .TP
 472 .B A9
 473 .BR epoll_wait (2)
 474 からイベントを受け取ることは、
 475 そのファイルディスクリプタが要求された I/O 操作に対して準備済みである、
 476 ということをユーザに示すものである。
 477 次の (ブロックしない) read/write で
 478 .B EAGAIN
 479 を受け取るまではファイルディスクリプタは準備済みであると
 480 考えなければならない。
 481 そのファイルディスクリプタをいつどのように使うかは、
 482 全くユーザに任されてる。
 483 .sp
 484 パケット指向やトークン指向のファイル (例えば、データグラムソケット、
 485 canonical モードの端末) では、
 486 読み込み用 / 書き込み用の I/O 空間の末尾を検知する唯一の方法は
 487 .B EAGAIN
 488 になるまで read/write を行うことである。
 489 .sp
 490 ストリーム指向のファイル (例えば、パイプ、FIFO、ストリームソケット) では、
 491 読み込み用 / 書き込み用の I/O 空間が使い尽くされた状態は、
 492 対象となるファイルディスクリプタから読み込んだデータ量または
 493 書き込んだデータ量をチェックすることでも検知できる。
 494 例えば、ある特定の量のデータを読み込むために
 495 .BR read (2)
 496 を呼んだときに、
 497 .BR read (2)
 498 が返したバイト数がそれより少なかった場合、
 499 そのファイルディスクリプタの読み込み用 I/O 空間が
 500 使い尽くされたことが分かる。
 501 .BR write (2)
 502 を使って書き込みをするときも、同じことが言える
 503 (監視しているファイルディスクリプタが常にストリーム指向のファイルを
 504 参照していることを保証できない場合には、後者の手法の使用を避けること)。
 505 .SS ありがちな落とし穴と回避方法
 506 .TP
 507 .B o 飢餓 (starvation) (エッジトリガ)
 508 .PP
 509 大きな I/O 空間がある場合、
 510 その I/O 空間のデータを全て処理 (drain) しようとすると、
 511 他のファイルが処理されず、飢餓を発生させることがある
 512 (この問題は
 513 .B epoll
 514 に固有のものではない)。
 515 .PP
 516 この問題の解決法は、準備済み状態のリストを管理して、
 517 関連する data 構造体の中でファイルディスクリプタが
 518 利用可能であるとマークすることである。
 519 それによって、利用可能なすべてのファイルの中で
 520 どのファイルを処理する必要があるかを憶えることができ、
 521 しかも順番に処理 (round robin) することができる。
 522 既に利用可能であるファイルディスクリプタに対して
 523 それ以後に受け取るイベントを無視することもできる。
 524 .TP
 525 .B o イベントキャッシュを使っている場合
 526 .PP
 527 イベントキャッシュを使っている場合、
 528 または
 529 .BR epoll_wait (2)
 530 から返された全てのファイルディスクリプタを格納している場合、
 531 クローズされたことを動的にマークする
 532 (つまり前のイベントの処理によってマークされる) 方法を提供すべきである。
 533 .BR epoll_wait (2)
 534 から 100 個のイベントを受け取り、
 535 イベント #47 ではある条件でイベント #13 が閉じられると仮定する。
 536 イベント #13 の構造体を削除しファイルディスクリプタを
 537 .BR close (2)
 538 すると、イベントキャッシュはそのファイルディスクリプタを待つイベントが
 539 存在するといって、混乱が起きる。
 540 .PP
 541 この問題を解決する 1 つの方法は、イベント 47 の処理をしている間に、
 542 ファイルディスクリプタ 13 を削除して
 543 .BR close (2)
 544 するために
 545 .BR epoll_ctl ( EPOLL_CTL_DEL )
 546 を呼び出し、関連付けられた data 構造体を削除済みとマークして、
 547 クリーンアップリストにリンクすることである。
 548 バッチ処理の中でファイルディスクリプタ 13 についての
 549 他のイベントを見つけた場合、
 550 そのファイルディスクリプタが以前に削除されたものであると分かるので、
 551 混乱は起きない。
 552 .SH バージョン
 553 .B epoll
 554 API は Linux カーネル 2.5.44 に導入された。
 555 .\" インタフェースは Linux カーネル 2.5.66 で確定されるべきである。
 556 glibc でのサポートはバージョン 2.3.2 で追加された。
 557 .SH 準拠
 558 .B epoll
 559 API は Linux 固有である。
 560 他のシステムでも同様の機構が提供されている場合がある。
 561 例えば、FreeBSD の
 562 .I kqueue
 563 や Solaris の
 564 .I /dev/poll
 565 などである。
 566 .SH 関連項目
 567 .BR epoll_create (2),
 568 .BR epoll_create1 (2),
 569 .BR epoll_ctl (2),
 570 .BR epoll_wait (2)