18.3. select — I/O 処理の完了を待機する


This module provides access to the select() and poll() functions available in most operating systems, devpoll() available on Solaris and derivatives, 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.

注釈

The selectors module allows high-level and efficient I/O multiplexing, built upon the select module primitives. Users are encouraged to use the selectors module instead, unless they want precise control over the OS-level primitives used.

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

exception select.error

A deprecated alias of OSError.

バージョン 3.3 で変更: Following PEP 3151, this class was made an alias of OSError.

select.devpoll()

(Only supported on Solaris and derivatives.) Returns a /dev/poll polling object; see section /dev/poll Polling Objects below for the methods supported by devpoll objects.

devpoll() objects are linked to the number of file descriptors allowed at the time of instantiation. If your program reduces this value, devpoll() will fail. If your program increases this value, devpoll() may return an incomplete list of active file descriptors.

The new file descriptor is non-inheritable.

バージョン 3.3 で追加.

バージョン 3.4 で変更: The new file descriptor is now non-inheritable.

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

(Only supported on Linux 2.5.44 and newer.) Return an edge polling object, which can be used as Edge or Level Triggered interface for I/O events. sizehint and flags are deprecated and completely ignored.

See the エッジおよびレベルトリガポーリング (epoll) オブジェクト section below for the methods supported by epolling objects.

epoll objects support the context management protocol: when used in a with statement, the new file descriptor is automatically closed at the end of the block.

The new file descriptor is non-inheritable.

バージョン 3.3 で変更: Added the flags parameter.

バージョン 3.4 で変更: Support for the with statement was added. The new file descriptor is now non-inheritable.

バージョン 3.4 で撤廃: The flags parameter. select.EPOLL_CLOEXEC is used by default now. Use os.set_inheritable() to make the file descriptor inheritable.

select.poll()

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

select.kqueue()

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

The new file descriptor is non-inheritable.

バージョン 3.4 で変更: The new file descriptor is now non-inheritable.

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

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

バージョン 3.5 で変更: The function is now retried with a recomputed timeout when interrupted by a signal, except if the signal handler raises an exception (see PEP 475 for the rationale), instead of raising InterruptedError.

select.PIPE_BUF

The minimum number of bytes which can be written without blocking to a pipe when the pipe has been reported as ready for writing by select(), poll() or another interface in this module. This doesn’t apply to other kind of file-like objects such as sockets.

This value is guaranteed by POSIX to be at least 512. Availability: Unix.

バージョン 3.2 で追加.

18.3.1. /dev/poll Polling Objects

Solaris and derivatives have /dev/poll. While select() is O(highest file descriptor) and poll() is O(number of file descriptors), /dev/poll is O(active file descriptors).

/dev/poll behaviour is very close to the standard poll() object.

devpoll.close()

Close the file descriptor of the polling object.

バージョン 3.4 で追加.

devpoll.closed

True if the polling object is closed.

バージョン 3.4 で追加.

devpoll.fileno()

Return the file descriptor number of the polling object.

バージョン 3.4 で追加.

devpoll.register(fd[, eventmask])

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

eventmask is an optional bitmask describing the type of events you want to check for. The constants are the same that with poll() object. The default value is a combination of the constants POLLIN, POLLPRI, and POLLOUT.

警告

Registering a file descriptor that’s already registered is not an error, but the result is undefined. The appropriate action is to unregister or modify it first. This is an important difference compared with poll().

devpoll.modify(fd[, eventmask])

This method does an unregister() followed by a register(). It is (a bit) more efficient that doing the same explicitly.

devpoll.unregister(fd)

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

Attempting to remove a file descriptor that was never registered is safely ignored.

devpoll.poll([timeout])

Polls the set of registered file descriptors, and returns a possibly-empty list containing (fd, event) 2-tuples for the descriptors that have events or errors to report. fd is the file descriptor, and event is a bitmask with bits set for the reported events for that descriptor — POLLIN for waiting input, POLLOUT to indicate that the descriptor can be written to, and so forth. An empty list indicates that the call timed out and no file descriptors had any events to report. If timeout is given, it specifies the length of time in milliseconds which the system will wait for events before returning. If timeout is omitted, -1, or None, the call will block until there is an event for this poll object.

バージョン 3.5 で変更: The function is now retried with a recomputed timeout when interrupted by a signal, except if the signal handler raises an exception (see PEP 475 for the rationale), instead of raising InterruptedError.

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

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

eventmask

定数 意味
EPOLLIN 読み込み可能
EPOLLOUT 書き込み可能
EPOLLPRI 緊急の読み出しデータ
EPOLLERR 設定された fd にエラー状態が発生した
EPOLLHUP 設定された fd がハングアップした
EPOLLET エッジトリガ動作に設定する。デフォルトではレベルトリガ動作
EPOLLONESHOT 1ショット動作に設定する。1回イベントが取り出されたら、その fd が内部で無効になる
EPOLLEXCLUSIVE Wake only one epoll object when the associated fd has an event. The default (if this flag is not set) is to wake all epoll objects polling on a fd.
EPOLLRDHUP Stream socket peer closed connection or shut down writing half of connection.
EPOLLRDNORM EPOLLIN と同じ
EPOLLRDBAND priority data band を読み込める。
EPOLLWRNORM EPOLLOUT と同じ
EPOLLWRBAND priority data に書き込みできる。
EPOLLMSG 無視される。
epoll.close()

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

epoll.closed

True if the epoll object is closed.

epoll.fileno()

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

epoll.fromfd(fd)

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

epoll.register(fd[, eventmask])

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

epoll.modify(fd, eventmask)

Modify a registered file descriptor.

epoll.unregister(fd)

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

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

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

バージョン 3.5 で変更: The function is now retried with a recomputed timeout when interrupted by a signal, except if the signal handler raises an exception (see PEP 475 for the rationale), instead of raising InterruptedError.

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

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

poll.register(fd[, eventmask])

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

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

定数 意味
POLLIN 読み出し可能なデータが存在する
POLLPRI 緊急の読み出し可能なデータが存在する
POLLOUT 書き出しの準備ができている: 書き出し処理がブロックしない
POLLERR 何らかのエラー状態
POLLHUP ハングアップ
POLLRDHUP Stream socket peer closed connection, or shut down writing half of connection
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 OSError exception with errno ENOENT to be raised.

poll.unregister(fd)

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

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

poll.poll([timeout])

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

バージョン 3.5 で変更: The function is now retried with a recomputed timeout when interrupted by a signal, except if the signal handler raises an exception (see PEP 475 for the rationale), instead of raising InterruptedError.

18.3.4. kqueue オブジェクト

kqueue.close()

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

kqueue.closed

True if the kqueue object is closed.

kqueue.fileno()

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

kqueue.fromfd(fd)

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

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

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

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

バージョン 3.5 で変更: The function is now retried with a recomputed timeout when interrupted by a signal, except if the signal handler raises an exception (see PEP 475 for the rationale), instead of raising InterruptedError.

18.3.5. 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() method. 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_READKQ_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

ユーザー定義値。