このモジュールでは、ほとんどのオペレーティングシステムで利用可能な select() および poll() 関数、 Linux 2.5+ で利用可能な epoll() 、多くのBSDで利用可能な kqueue() 関数に対するアクセスを提供しています。 Windows 上ではソケットに対してしか動作しないので注意してください; その他のオペレーティングシステムでは、他のファイル形式でも (特に Unixではパイプにも) 動作します。通常のファイルに対して適用し、最後にファイルを読み出した時から内容が増えているかを決定するために使うことはできません。
このモジュールでは以下の内容を定義しています:
エラーが発生したときに送出される例外です。エラーに付属する値は、 errno からとったエラーコードを表す数値とそのエラーコードに対応する文字列からなるペアで、C 関数の perror() が出力するものと同様です。
(Linux 2.5.44 以降でのみサポート) エッジポーリング(edge polling)オブジェクトを返します。このオブジェクトは、 I/O イベントのエッジトリガもしくはレベルトリガインタフェースとして使うことができます。エッジポーリングオブジェクトが提供しているメソッドについては、 エッジおよびレベルトリガポーリング (epoll) オブジェクト 節を参照してください。
バージョン 2.6 で追加.
(全てのオペレーティングシステムでサポートされているわけではありません) ポーリングオブジェクトを返します。このオブジェクトはファイル記述子を登録したり登録解除したりすることができ、ファイル記述子に対する I/O イベント発生をポーリングすることができます; ポーリングオブジェクトが提供しているメソッドについては ポーリングオブジェクト 節を参照してください。
(BSD でのみサポート) カーネルキュー(kernel queue)オブジェクトを返します。カーネルキューオブジェクトが提供しているメソッドについては、 kqueue オブジェクト 節を参照してください。
バージョン 2.6 で追加.
(BSD でのみサポート) カーネルイベント(kernel event)オブジェクトを返します。カーネルイベントオブジェクトが提供しているメソッドについては、 kevent オブジェクト 節を参照してください。
バージョン 2.6 で追加.
Unix の select() システムコールに対する直接的なインタフェースです。最初の 3 つの引数は ‘待機可能オブジェクト’ からなるシーケンスです: 待機可能オブジェクトとは、ファイル記述子を表す整数値か、引数なしで整数を返すメソッド fileno() を持つオブジェクトです。
引数に空のシーケンスを指定してもかまいませんが、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() や poll() などのインタフェースにより書き込み可能になったと報告されたファイルは、 PIPE_BUF バイトまではブロックしないで書き込みできることが保証されます。この値は POSIX では最低でも 512 であることが保証されています。
利用可能な環境: Unix
バージョン 2.7 で追加.
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 オブジェクトの制御用ファイル記述子を閉じる。
制御用ファイル記述子の番号を返す。
fd から epoll オブジェクトを作成する。
epoll オブジェクトにファイル記述子 fd を登録する。
ノート
ポーリングオブジェクト の register とは異なり、登録済みのファイル記述子を登録しようとすると IOError が発生します。
ファイル記述子 fd の登録を変更する。
epoll オブジェクトから登録されたファイル記述子 fd を削除する。
イベントを待つ。 timeout はタイムアウト時間で、単位は秒(float型) です。
poll() システムコールはほとんどの Unix システムでサポートされており、非常に多数のクライアントに同時にサービスを提供するようなネットワークサーバが高いスケーラビリティを持てるようにしています。 poll() は対象のファイル記述子を列挙するだけでよいため、良くスケールします。一方、 select() はビット対応表を構築し、対象ファイルの記述子に対応するビットを立て、その後全ての対応表の全てのビットを線形探索します。 select() は O(最大のファイル記述子番号) なのに対し、 poll() は O(対象とするファイル記述子の数) で済みます。
ファイル記述子をポーリングオブジェクトに登録します。これ以降の poll() メソッド呼び出しでは、そのファイル記述子に処理待ち中の I/O イベントがあるかどうかを監視します。 fd は整数か、整数値を返す fileno() メソッドを持つオブジェクトを取ります。ファイルオブジェクトも fileno() を実装しているので、引数として使うことができます。
eventmask はオプションのビットマスクで、どの種類の I/O イベントを監視したいかを記述します。この値は以下の表で述べる定数 POLLIN 、 POLLPRI 、および POLLOUT の組み合わせにすることができます。ビットマスクを指定しない場合、標準の値が使われ、 3 種類のイベント全てに対して監視が行われます。
定数 | 意味 |
---|---|
POLLIN | 読み出し可能なデータが存在する |
POLLPRI | 緊急の読み出し可能なデータが存在する |
POLLOUT | 書き出しの準備ができている: 書き出し処理がブロックしない |
POLLERR | 何らかのエラー状態 |
POLLHUP | ハングアップ |
POLLNVAL | 無効な要求: 記述子が開かれていない |
登録済みのファイル記述子を登録してもエラーにはならず、一度だけ登録した場合と同じ効果になります。
登録されているファイル記述子 fd を変更する。これは、 register(fd, eventmask) と同じ効果を持ちます。登録されていないファイル記述子に対してこのメソッドを呼び出すと、 errno ENOENT で IOError 例外が発生します。
バージョン 2.6 で追加.
ポーリングオブジェクトによって追跡中のファイル記述子を登録解除します。 register() メソッドと同様に、 fd は整数か、整数値を返す fileno() メソッドを持つオブジェクトを取ります。
登録されていないファイル記述子を登録解除しようとすると KeyError 例外が送出されます。
登録されたファイル記述子に対してポーリングを行い、報告すべき I/O イベントまたはエラーの発生したファイル記述子毎に 2 要素のタプル (fd, event) からなるリストを返します。リストは空になることもあります。 fd はファイル記述子で、 event は該当するファイル記述子について報告されたイベントを表すビットマスクです — 例えば POLLIN は入力待ちを示し、 POLLOUT はファイル記述子に対する書き込みが可能を示す、などです。空のリストは呼び出しがタイムアウトしたか、報告すべきイベントがどのファイル記述子でも発生しなかったことを示します。 timeout が与えられた場合、処理を戻すまで待機する時間の長さをミリ秒単位で指定します。 timeout が省略されたり、負の値であったり、あるいは None の場合、そのポーリングオブジェクトが監視している何らかのイベントが発生するまでブロックします。
kqueue オブジェクトの制御用ファイル記述子を閉じる。
制御用ファイル記述子の番号を返す。
与えられたファイル記述子から、kqueue オブジェクトを作成する。
kevent に対する低レベルのインタフェース
http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
イベントを特定するための値。この値は、フィルタにもよりますが、大抵の場合はファイル記述子です。コンストラクタでは、 ident として、整数値か fileno() メソッドを持ったオブジェクトを渡せます。 kevent は内部で整数値を保存します。
カーネルフィルタの名前。
定数 | 意味 |
---|---|
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 | 任意のタイマを設定する |
フィルタアクション。
定数 | 意味 |
---|---|
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 | 戻り値を参照 |
フィルタ依存のフラグ。
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 | リンク状態が不正 |
フィルタ固有のデータ。
ユーザー定義値。