# 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=None]) → eventlist

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

  - changelist は kevent オブジェクトのイテラブルまたは `None`
  - max_events は 0 または正の整数
  - timeout はタイムアウト秒数 (float を利用可能)

## 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`

  ユーザー定義値。