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() オブジェクトと同じ定数が使われます。デフォルト値は定数 POLLINPOLLPRI 、および 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 イベントを監視したいかを記述します。この値は以下の表で述べる定数 POLLINPOLLPRI 、および POLLOUT の組み合わせにすることができます。ビットマスクを指定しない場合、標準の値が使われ、 3 種類のイベント全てに対して監視が行われます。

定数

意味

POLLIN

読み出し可能なデータが存在する

POLLPRI

緊急の読み出し可能なデータが存在する

POLLOUT

書き出しの準備ができている: 書き出し処理がブロックしない

POLLERR

何らかのエラー状態

POLLHUP

ハングアップ

POLLRDHUP

ストリームソケットの他端が接続を切断したか、接続の書き込み側のシャットダウンを行った。

POLLNVAL

無効な要求: 記述子が開かれていない

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

poll.modify(fd, eventmask)

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

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_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 フィルタフラグ (macOS では利用不可):

定数

意味

KQ_NOTE_LINKUP

リンクアップしている

KQ_NOTE_LINKDOWN

リンクダウンしている

KQ_NOTE_LINKINV

リンク状態が不正

kevent.data

フィルタ固有のデータ。

kevent.udata

ユーザー定義値。