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

This module provides access to the "select()" and "poll()" functions
available in most operating systems, "epoll()" available on Linux 2.5+
and "kqueue()" available on most BSD. Note that on Windows, it only
works for sockets; on other operating systems, it also works for other
file types (in particular, on Unix, it works on pipes). It cannot be
used on regular files to determine whether a file has grown since it
was last read.

このモジュールは以下を定義します:

exception select.error

   The exception raised when an error occurs.  The accompanying value
   is a pair containing the numeric error code from "errno" and the
   corresponding string, as would be printed by the C function
   "perror()".

select.epoll([sizehint=-1])

   (Only supported on Linux 2.5.44 and newer.)  Returns an edge
   polling object, which can be used as Edge or Level Triggered
   interface for I/O events; see section エッジおよびレベルトリガポー
   リング (epoll) オブジェクト below for the methods supported by
   epolling objects.

   バージョン 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 つの空のリストが返されます。

   Among the acceptable object types in the sequences are Python file
   objects (e.g. "sys.stdin", or objects returned by "open()" or
   "os.popen()"), socket objects returned by "socket.socket()".  You
   may also define a *wrapper* class yourself, as long as it has an
   appropriate "fileno()" method (that really returns a file
   descriptor, not just a random integer).

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

select.PIPE_BUF

   Files reported as ready for writing by "select()", "poll()" or
   similar interfaces in this module are guaranteed to not block on a
   write of up to "PIPE_BUF" bytes. This value is guaranteed by POSIX
   to be at least 512.  Availability: Unix.

   バージョン 2.7 で追加.


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

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

   *eventmask*

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

epoll.close()

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

epoll.fileno()

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

epoll.fromfd(fd)

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

epoll.register(fd[, eventmask])

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

   注釈: Registering a file descriptor that’s already registered
     raises an IOError – contrary to ポーリングオブジェクト’s
     register.

epoll.modify(fd, eventmask)

   Modify a register file descriptor.

epoll.unregister(fd)

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

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

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


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

"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)

   Modifies an already registered fd. This has the same effect as
   "register(fd, eventmask)".  Attempting to modify a file descriptor
   that was never registered causes an "IOError" exception with errno
   "ENOENT" to be raised.

   バージョン 2.6 で追加.

poll.unregister(fd)

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

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

poll.poll([timeout])

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


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

kqueue.close()

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

kqueue.fileno()

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

kqueue.fromfd(fd)

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

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

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

   * *changelist* は kevent オブジェクトのイテラブルまたは "None"

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

   * *timeout* はタイムアウト秒数 (float を利用可能)


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

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

kevent.ident

   Value used to identify the event. The interpretation depends on the
   filter but it’s usually the file descriptor. In the constructor
   ident can either be an int or an object with a fileno() function.
   kevent stores the integer internally.

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

   ユーザー定義値。
