16.1. "select" --- I/O 処理の完了を待機する
*******************************************

このモジュールでは、ほとんどのオペレーティングシステムで利用可能な
"select()" および "poll()" 関数、 Linux 2.5+ で利用可能な "epoll()" 、
多くの BSD で利用可能な "kqueue()" 関数に対するアクセスを提供していま
す。 Windows 上ではソケットに対してしか動作しないので注意してください;
その他のオペレーティングシステムでは、他のファイル形式でも (特に Unix
ではパイプにも) 動作します。通常のファイルに対して適用し、最後にファイ
ルを読み出した時から内容が増えているかを決定するために使うことはできま
せん。

以下はこのモジュールの定義:

exception select.error

   エラーが発生したときに送出される例外です。エラーに付属する値は、
   "errno" からとったエラーコードを表す数値とそのエラーコードに対応す
   る文字列 (C 関数の "perror()" の出力相当のもの) からなるペアです。

select.epoll([sizehint=-1])

   (Linux 2.5.44 以降でのみサポート) エッジポーリング(edge polling) オ
   ブジェクトを返します。このオブジェクトは、 I/O イベントのエッジトリ
   ガもしくはレベルトリガインタフェースとして使うことができます。エッ
   ジポーリングオブジェクトが提供しているメソッドについては、 エッジお
   よびレベルトリガポーリング (epoll) オブジェクト 節を参照してくださ
   い。

   バージョン 2.6 で追加.

select.poll()

   (全てのオペレーティングシステムでサポートされているわけではありませ
   ん) ポーリングオブジェクトを返します。このオブジェクトはファイル記
   述子を登録したり登録解除したりすることができ、ファイル記述子に対す
   る I/O イベント発生をポーリングすることができます; ポーリングオブジ
   ェクトが提供しているメソッドについては ポーリングオブジェクト 節を
   参照してください。

select.kqueue()

   (BSD でのみサポート) カーネルキュー(kernel queue)オブジェクトを返し
   ます。カーネルキューオブジェクトが提供しているメソッドについては、
   kqueue オブジェクト 節を参照してください。

   バージョン 2.6 で追加.

select.kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)

   (BSD でのみサポート) カーネルイベント(kernel event)オブジェクトを返
   します。カーネルイベントオブジェクトが提供しているメソッドについて
   は、 kevent オブジェクト 節を参照してください。

   バージョン 2.6 で追加.

select.select(rlist, wlist, xlist[, timeout])

   Unix の "select()" システムコールに対する直接的なインタフェースです
   。最初の 3 つの引数は '待機可能オブジェクト' からなるシーケンスです
   : 待機可能オブジェクトとは、ファイル記述子を表す整数値か、そのよう
   な整数を返す引数なしメソッド "fileno()" を持つオブジェクトです。

   * *rlist*: 読み込み可能になるまで待機

   * *wlist*: 書き込み可能になるまで待機

   * *xlist*: "例外状態 (exceptional condition)" になるまで待機 ("例
     外 状態" については、システムのマニュアルページを参照してください
     )

   引数に空のシーケンスを指定してもかまいませんが、3 つの引数全てを空
   のシーケンスにしてもよいかどうかはプラットフォームに依存します
   (Unix では動作し、Windows では動作しないことが知られています)。オプ
   ションの *timeout* 引数にはタイムアウトまでの秒数を浮動小数点数で指
   定します。*timeout* 引数が省略された場合、関数は少なくとも一つのフ
   ァイル記述子が何らかの準備完了状態になるまでブロックします。
   *timeout* に 0 を指定した場合は、ポーリングを行いブロックしないこと
   を示します。

   戻り値は準備完了状態のオブジェクトからなる 3 つのリストです: したが
   ってこのリストはそれぞれ関数の最初の 3 つの引数のサブセットになりま
   す。ファイル記述子のいずれも準備完了にならないままタイムアウトした
   場合、3 つの空のリストが返されます。

   シーケンスの中に含めることのできるオブジェクトは Python ファイルオ
   ブジェクト (例えば "sys.stdin" や、 "open()" または "os.popen()" が
   返すオブジェクト)、 "socket.socket()" が返すソケットオブジェクトで
   す。ラッパー (*wrapper*) クラスを自分で定義することもできます。この
   場合、適切な (まったくデタラメな数ではなく本物のファイル記述子を返
   す) "fileno()" メソッドを持つ必要があります。

   注釈: "select()" は Windows のファイルオブジェクトを受理しません
     が、ソ ケットは受理します。 Windows では、背後の "select()" 関数
     は WinSock ライブラリで提供されており、 WinSock によって生成され
     たも のではないファイル記述子を扱うことができないのです。

select.PIPE_BUF

   このモジュールの "select()" や "poll()" などのインタフェースにより
   書き込み可能になったと報告されたファイルは、 "PIPE_BUF" バイトまで
   はブロックしないで書き込みできることが保証されます。この値は POSIX
   では最低でも 512 であることが保証されています。 利用可能な環境:
   Unix

   バージョン 2.7 で追加.


16.1.1. エッジおよびレベルトリガポーリング (epoll) オブジェクト
===============================================================

   http://linux.die.net/man/4/epoll

   *eventmask*

   +-------------------------+-------------------------------------------------+
   | 定数                    | 意味                                            |
   |=========================|=================================================|
   | "EPOLLIN"               | 読み込み可能                                    |
   +-------------------------+-------------------------------------------------+
   | "EPOLLOUT"              | 書き込み可能                                    |
   +-------------------------+-------------------------------------------------+
   | "EPOLLPRI"              | 緊急の読み出しデータ                            |
   +-------------------------+-------------------------------------------------+
   | "EPOLLERR"              | 設定された fd にエラー状態が発生した            |
   +-------------------------+-------------------------------------------------+
   | "EPOLLHUP"              | 設定された fd がハングアップした                |
   +-------------------------+-------------------------------------------------+
   | "EPOLLET"               | エッジトリガ動作に設定する。デフォルトではレベ  |
   |                         | ルトリガ動作                                    |
   +-------------------------+-------------------------------------------------+
   | "EPOLLONESHOT"          | 1ショット動作に設定する。1回イベントが取り出さ  |
   |                         | れたら、その fd が内 部で無効になる             |
   +-------------------------+-------------------------------------------------+
   | "EPOLLRDNORM"           | "EPOLLIN" と同じ                                |
   +-------------------------+-------------------------------------------------+
   | "EPOLLRDBAND"           | priority data band を読み込める。               |
   +-------------------------+-------------------------------------------------+
   | "EPOLLWRNORM"           | "EPOLLOUT" と同じ                               |
   +-------------------------+-------------------------------------------------+
   | "EPOLLWRBAND"           | priority data に書き込みできる。                |
   +-------------------------+-------------------------------------------------+
   | "EPOLLMSG"              | 無視される。                                    |
   +-------------------------+-------------------------------------------------+

epoll.close()

   epoll オブジェクトの制御用ファイル記述子を閉じます。

epoll.fileno()

   制御用ファイル記述子の番号を返します。

epoll.fromfd(fd)

   *fd* から epoll オブジェクトを作成します。

epoll.register(fd[, eventmask])

   epoll オブジェクトにファイル記述子 *fd* を登録します。

   注釈: ポーリングオブジェクト の register とは異なり、登録済みのフ
     ァイル 記述子を登録しようとすると "IOError" が発生します。

epoll.modify(fd, eventmask)

   ファイル記述子 *fd* の登録を変更する。

epoll.unregister(fd)

   epoll オブジェクトから登録されたファイル記述子 *fd* を削除します。

epoll.poll([timeout=-1[, maxevents=-1]])

   イベントを待機します。*timeout* はタイムアウト時間で、単位は秒
   (float型) です。


16.1.2. ポーリングオブジェクト
==============================

"poll()" システムコールはほとんどの Unix システムでサポートされており
、非常に多数のクライアントに同時にサービスを提供するようなネットワーク
サーバが高いスケーラビリティを持てるようにしています。 "poll()" は対象
のファイル記述子を列挙するだけでよいため、良くスケールします。一方、
"select()" はビット対応表を構築し、対象ファイルの記述子に対応するビッ
トを立て、その後全ての対応表の全てのビットを線形探索します。
"select()" は O(最大のファイル記述子番号) なのに対し、 "poll()" は O(
対象とするファイル記述子の数) で済みます。

poll.register(fd[, eventmask])

   ファイル記述子をポーリングオブジェクトに登録します。これ以降の
   "poll()" メソッド呼び出しでは、そのファイル記述子に処理待ち中の I/O
   イベントがあるかどうかを監視します。 *fd* は整数か、整数値を返す
   "fileno()" メソッドを持つオブジェクトを取ります。ファイルオブジェク
   トも "fileno()" を実装しているので、引数として使うことができます。

   *eventmask* はオプションのビットマスクで、どの種類の I/O イベントを
   監視したいかを記述します。この値は以下の表で述べる定数 "POLLIN" 、
   "POLLPRI" 、および "POLLOUT" の組み合わせにすることができます。ビッ
   トマスクを指定しない場合、標準の値が使われ、 3 種類のイベント全てに
   対して監視が行われます。

   +---------------------+--------------------------------------------+
   | 定数                | 意味                                       |
   |=====================|============================================|
   | "POLLIN"            | 読み出し可能なデータが存在する             |
   +---------------------+--------------------------------------------+
   | "POLLPRI"           | 緊急の読み出し可能なデータが存在する       |
   +---------------------+--------------------------------------------+
   | "POLLOUT"           | 書き出しの準備ができている: 書き出し処理が |
   |                     | ブロックしない                             |
   +---------------------+--------------------------------------------+
   | "POLLERR"           | 何らかのエラー状態                         |
   +---------------------+--------------------------------------------+
   | "POLLHUP"           | ハングアップ                               |
   +---------------------+--------------------------------------------+
   | "POLLNVAL"          | 無効な要求: 記述子が開かれていない         |
   +---------------------+--------------------------------------------+

   登録済みのファイル記述子を登録してもエラーにはならず、一度だけ登録
   した場合と同じ効果になります。

poll.modify(fd, eventmask)

   登録されているファイル記述子 *fd* を変更する。これは、
   "register(fd, eventmask)" と同じ効果を持ちます。登録されていないフ
   ァイル記述子に対してこのメソッドを呼び出すと、 errno "ENOENT" で
   "IOError" 例外が発生します。

   バージョン 2.6 で追加.

poll.unregister(fd)

   ポーリングオブジェクトによって追跡中のファイル記述子を登録解除しま
   す。 "register()" メソッドと同様に、 *fd* は整数か、整数値を返す
   "fileno()" メソッドを持つオブジェクトを取ります。

   登録されていないファイル記述子を登録解除しようとすると "KeyError"
   例外が送出されます。

poll.poll([timeout])

   登録されたファイル記述子に対してポーリングを行い、報告すべき I/O イ
   ベントまたはエラーの発生したファイル記述子毎に 2 要素のタプル "(fd,
   event)" からなるリストを返します。リストは空になることもあります。
   *fd* はファイル記述子で、 *event* は該当するファイル記述子について
   報告されたイベントを表すビットマスクです --- 例えば "POLLIN" は入力
   待ちを示し、 "POLLOUT" はファイル記述子に対する書き込みが可能を示す
   、などです。空のリストは呼び出しがタイムアウトしたか、報告すべきイ
   ベントがどのファイル記述子でも発生しなかったことを示します。
   *timeout* が与えられた場合、処理を戻すまで待機する時間の長さをミリ
   秒単位で指定します。 *timeout* が省略されたり、負の値であったり、あ
   るいは "None" の場合、そのポーリングオブジェクトが監視している何ら
   かのイベントが発生するまでブロックします。


16.1.3. kqueue オブジェクト
===========================

kqueue.close()

   kqueue オブジェクトの制御用ファイル記述子を閉じる。

kqueue.fileno()

   制御用ファイル記述子の番号を返します。

kqueue.fromfd(fd)

   与えられたファイル記述子から、kqueue オブジェクトを作成する。

kqueue.control(changelist, max_events[, timeout]) -> eventlist

   kevent に対する低水準のインタフェース

   * changelist must be an iterable of kevent objects or "None"

   * *max_events* は 0 または正の整数

   * timeout in seconds (floats possible); the default is "None", to
     wait forever


16.1.4. kevent オブジェクト
===========================

https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2

kevent.ident

   イベントを特定するための値。この値は、フィルタにもよりますが、大抵
   の場合はファイル記述子です。コンストラクタでは、 ident として、整数
   値か "fileno()" メソッドを持ったオブジェクトを渡せます。 kevent は
   内部で整数値を保存します。

kevent.filter

   カーネルフィルタの名前。

   +-----------------------------+-----------------------------------------------+
   | 定数                        | 意味                                          |
   |=============================|===============================================|
   | "KQ_FILTER_READ"            | 記述子を受け取り、読み込めるデータが存在する  |
   |                             | 時に戻る                                      |
   +-----------------------------+-----------------------------------------------+
   | "KQ_FILTER_WRITE"           | 記述子を受け取り、書き込み可能な時に戻る      |
   +-----------------------------+-----------------------------------------------+
   | "KQ_FILTER_AIO"             | AIO リクエスト                                |
   +-----------------------------+-----------------------------------------------+
   | "KQ_FILTER_VNODE"           | *fflag* で監視されたイベントが1つ以上発生した |
   |                             | ときに戻る                                    |
   +-----------------------------+-----------------------------------------------+
   | "KQ_FILTER_PROC"            | プロセスID上のイベントを監視する              |
   +-----------------------------+-----------------------------------------------+
   | "KQ_FILTER_NETDEV"          | ネットワークデバイス上のイベントを監視する    |
   |                             | (Mac OS X では利用不可)                       |
   +-----------------------------+-----------------------------------------------+
   | "KQ_FILTER_SIGNAL"          | 監視しているシグナルがプロセスに届いたときに  |
   |                             | 戻る                                          |
   +-----------------------------+-----------------------------------------------+
   | "KQ_FILTER_TIMER"           | 任意のタイマを設定する                        |
   +-----------------------------+-----------------------------------------------+

kevent.flags

   フィルタアクション。

   +-----------------------------+-----------------------------------------------+
   | 定数                        | 意味                                          |
   |=============================|===============================================|
   | "KQ_EV_ADD"                 | イベントを追加または修正する                  |
   +-----------------------------+-----------------------------------------------+
   | "KQ_EV_DELETE"              | キューからイベントを取り除く                  |
   +-----------------------------+-----------------------------------------------+
   | "KQ_EV_ENABLE"              | control() がイベントを返すのを許可する        |
   +-----------------------------+-----------------------------------------------+
   | "KQ_EV_DISABLE"             | イベントを無効にする                          |
   +-----------------------------+-----------------------------------------------+
   | "KQ_EV_ONESHOT"             | イベントを最初の発生後無効にする              |
   +-----------------------------+-----------------------------------------------+
   | "KQ_EV_CLEAR"               | イベントを受け取った後で状態をリセットする    |
   +-----------------------------+-----------------------------------------------+
   | "KQ_EV_SYSFLAGS"            | 内部イベント                                  |
   +-----------------------------+-----------------------------------------------+
   | "KQ_EV_FLAG1"               | 内部イベント                                  |
   +-----------------------------+-----------------------------------------------+
   | "KQ_EV_EOF"                 | フィルタ依存のEOF状態                         |
   +-----------------------------+-----------------------------------------------+
   | "KQ_EV_ERROR"               | 戻り値を参照                                  |
   +-----------------------------+-----------------------------------------------+

kevent.fflags

   フィルタ依存のフラグ。

   "KQ_FILTER_READ" と "KQ_FILTER_WRITE" フィルタのフラグ:

   +------------------------------+----------------------------------------------+
   | 定数                         | 意味                                         |
   |==============================|==============================================|
   | "KQ_NOTE_LOWAT"              | ソケットバッファの最低基準値                 |
   +------------------------------+----------------------------------------------+

   "KQ_FILTER_VNODE" フィルタのフラグ:

   +------------------------------+----------------------------------------------+
   | 定数                         | 意味                                         |
   |==============================|==============================================|
   | "KQ_NOTE_DELETE"             | *unlink()* が呼ばれた                        |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_WRITE"              | 書き込みが発生した                           |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_EXTEND"             | ファイルのサイズが拡張された                 |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_ATTRIB"             | 属性が変更された                             |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_LINK"               | リンクカウントが変更された                   |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_RENAME"             | ファイル名が変更された                       |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_REVOKE"             | ファイルアクセスが破棄された                 |
   +------------------------------+----------------------------------------------+

   "KQ_FILTER_PROC" フィルタフラグ:

   +------------------------------+----------------------------------------------+
   | 定数                         | 意味                                         |
   |==============================|==============================================|
   | "KQ_NOTE_EXIT"               | プロセスが終了した                           |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_FORK"               | プロセスが *fork()* を呼び出した             |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_EXEC"               | プロセスが新しいプロセスを実行した           |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_PCTRLMASK"          | 内部フィルタフラグ                           |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_PDATAMASK"          | 内部フィルタフラグ                           |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_TRACK"              | *fork()* の呼び出しを超えてプロセスを監視す  |
   |                              | る                                           |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_CHILD"              | *NOTE_TRACK* に対して子プロセスに渡される    |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_TRACKERR"           | 子プロセスにアタッチできなかった             |
   +------------------------------+----------------------------------------------+

   "KQ_FILTER_NETDEV" フィルタフラグ (Mac OS X では利用不可):

   +------------------------------+----------------------------------------------+
   | 定数                         | 意味                                         |
   |==============================|==============================================|
   | "KQ_NOTE_LINKUP"             | リンクアップしている                         |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_LINKDOWN"           | リンクダウンしている                         |
   +------------------------------+----------------------------------------------+
   | "KQ_NOTE_LINKINV"            | リンク状態が不正                             |
   +------------------------------+----------------------------------------------+

kevent.data

   フィルタ固有のデータ。

kevent.udata

   ユーザー定義値。
