# `select` --- I/O 処理の完了を待機する

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

注釈

`selectors` モジュールにより、`select` モジュールプリミティブに基づく高水準かつ効率的な I/O の多重化が行うことが出来ます。 OS レベルプリミティブを使用した正確な制御を求めない限り、代わりに `selectors` を使用することが推奨されます。

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

exception `select.``error`

  `OSError` の非推奨のエイリアスです。

  バージョン 3.3 で変更: PEP 3151 に基づき、このクラスは `OSError` のエイリアスになりました。

`select.``devpoll`()

  (Solaris およびその派生でのみサポートされています) `/dev/poll` ポーリングオブジェクトを返します。 ポーリングオブジェクトが提供しているメソッドについては ポーリングオブジェクト 節を参照してください。

  `devpoll()` オブジェクトはインスタンス化時に許されるファイル記述子の数にリンクされます。 プログラムがこの値を減らす場合 `devpoll()` は失敗します。 プログラムがこの値を増やす場合 `devpoll()` は有効なファイル記述子の不完全なリストを返すことがあります。

  新しいファイル記述子は 継承不可 です。

  バージョン 3.3 で追加.

  バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

`select.``epoll`(sizehint=- 1, flags=0)

  (Linux 2.5.44 以降でのみサポート) エッジポーリング (edge polling) オブジェクトを返します。 このオブジェクトは、 I/O イベントのエッジトリガもしくはレベルトリガインターフェースとして使えます。

  sizehint informs epoll about the expected number of events to be registered. It must be positive, or `-1` to use the default. It is only used on older systems where `epoll_create1()` is not available; otherwise it has no effect (though its value is still checked).

  flags is deprecated and completely ignored. However, when supplied, its value must be `0` or `select.EPOLL_CLOEXEC`, otherwise `OSError` is raised.

  エッジポーリングオブジェクトが提供しているメソッドについては エッジおよびレベルトリガポーリング (epoll) オブジェクト 節を参照してください。

  `epoll` オブジェクトはコンテキストマネジメントプロトコルをサポートしています。 `with` 文内で使用された場合、新たなファイル記述子はブロックの最後で自動的に閉じられます。

  新しいファイル記述子は 継承不可 です。

  バージョン 3.3 で変更: flags 引数が追加されました。

  バージョン 3.4 で変更: `with` 文のサポートが追加されました。新しいファイル記述子が継承不可になりました。

  バージョン 3.4 で非推奨: flags パラメータ。 現在ではデフォルトで `select.EPOLL_CLOEXEC` が使われます。 ファイルディスクリプタを継承可能にするには `os.set_inheritable()` を使ってください。

`select.``poll`()

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

`select.``kqueue`()

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

  新しいファイル記述子は 継承不可 です。

  バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

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

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

`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 によって生成されたものではないファイル記述子を扱うことができないのです。

  バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、 `InterruptedError` を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 を見てください)。

`select.``PIPE_BUF`

  `select()`, `poll()` またはこのモジュールの別のインターフェースによってパイプが書き込む準備ができていると報告された時に、ブロックせずにパイプに書き込むことのできる最小のバイト数。これはソケットなどの他の種類の file-like オブジェクトには適用されません。

  この値は POSIX により少なくとも512であることが保証されています。

  利用可能な環境: Unix

  バージョン 3.2 で追加.

## `/dev/poll` ポーリングオブジェクト

Solaris とその派生は、`/dev/poll` を持っています。 `select()` が O(最大のファイル記述子) 、 `poll()` が O(ファイル記述子の数) である一方、 `/dev/poll` は O(アクティブなファイル記述子) です。

`/dev/poll` の挙動は標準的な `poll()` オブジェクトに非常に近いです。

`devpoll.``close`()

  ポーリングオブジェクトのファイル記述子を閉じます。

  バージョン 3.4 で追加.

`devpoll.``closed`

  ポーリングオブジェクトが閉じている場合 `True` です。

  バージョン 3.4 で追加.

`devpoll.``fileno`()

  ポーリングオブジェクトのファイル記述子番号を返します。

  バージョン 3.4 で追加.

`devpoll.``register`(fd[, eventmask])

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

  eventmask はオプションのビットマスクで、どの種類の I/O イベントを監視したいかを記述します。 `poll()` オブジェクトと同じ定数が使われます。デフォルト値は定数 `POLLIN` 、 `POLLPRI` 、および `POLLOUT` の組み合わせです。

  警告

  登録済みのファイル記述子を登録してもエラーにはなりませんが、結果は未定義です。適切なアクションは、最初に unregister するか modify することです。これは `poll()` と比較した場合の重要な違いです。

`devpoll.``modify`(fd[, eventmask])

  このメソッドは `unregister()` に続いて `register()` を行います。 同じことを明示的に行うよりも (少し) 効率的です。

`devpoll.``unregister`(fd)

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

  登録されていないファイル記述子の削除を試みるのは安全に無視されます。

`devpoll.``poll`([timeout])

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

  バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、 `InterruptedError` を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 を見てください)。

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

> https://linux.die.net/man/4/epoll

> eventmask

> 定数 | 意味
> --- | ---
> `EPOLLIN` | 読み込み可能
> `EPOLLOUT` | 書き込み可能
> `EPOLLPRI` | 緊急の読み出しデータ
> `EPOLLERR` | 設定された fd にエラー状態が発生した
> `EPOLLHUP` | 設定された fd がハングアップした
> `EPOLLET` | エッジトリガ動作に設定する。デフォルトではレベルトリガ動作
> `EPOLLONESHOT` | 1ショット動作に設定する。1回イベントが取り出されたら、その fd が内部で無効になる
> `EPOLLEXCLUSIVE` | 関連づけられた fd にイベントがある場合、1 つの epoll オブジェクトのみを起こします。デフォルトでは (このフラグが設定されていない場合には)、fd に対してポーリングするすべての epoll オブジェクトを起こします。
> `EPOLLRDHUP` | ストリームソケットの他端が接続を切断したか、接続の書き込み側のシャットダウンを行った。
> `EPOLLRDNORM` | `EPOLLIN` と同じ
> `EPOLLRDBAND` | 優先データバンドを読み込める。
> `EPOLLWRNORM` | `EPOLLOUT` と同じ
> `EPOLLWRBAND` | 優先データに書き込みできる。
> `EPOLLMSG` | 無視される。

> バージョン 3.6 で追加: `EPOLLEXCLUSIVE` was added. It's only supported by Linux Kernel 4.5 or later.

`epoll.``close`()

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

`epoll.``closed`

  epoll オブジェクトが閉じている場合 True です。

`epoll.``fileno`()

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

`epoll.``fromfd`(fd)

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

`epoll.``register`(fd[, eventmask])

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

`epoll.``modify`(fd, eventmask)

  登録されたファイル記述子変更します。

`epoll.``unregister`(fd)

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

  バージョン 3.9 で変更: The method no longer ignores the `EBADF` error.

`epoll.``poll`(timeout=None, maxevents=- 1)

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

  バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、 `InterruptedError` を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 を見てください)。

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

`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` | ハングアップ
  `POLLRDHUP` | ストリームソケットの他端が接続を切断したか、接続の書き込み側のシャットダウンを行った。
  `POLLNVAL` | 無効な要求: 記述子が開かれていない

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

`poll.``modify`(fd, eventmask)

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

`poll.``unregister`(fd)

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

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

`poll.``poll`([timeout])

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

  バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、 `InterruptedError` を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 を見てください)。

## kqueue オブジェクト

`kqueue.``close`()

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

`kqueue.``closed`

  kqueue オブジェクトが閉じている場合 `True` です。

`kqueue.``fileno`()

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

`kqueue.``fromfd`(fd)

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

`kqueue.``control`(changelist, max_events[, timeout]) → eventlist

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

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

  - max_events は 0 または正の整数

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

  バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、 `InterruptedError` を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 を見てください)。

## 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` | ネットワークデバイス上のイベントを監視する (macOS では利用不可)
  `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` フィルタフラグ (macOS では利用不可):

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

`kevent.``data`

  フィルタ固有のデータ。

`kevent.``udata`

  ユーザー定義値。