select --- I/O 完了の待機¶
このモジュールでは、ほとんどのオペレーティングシステムで利用可能な select() および poll() 関数、Solaris やその派生で利用可能な devpoll() 、Linux 2.5+ で利用可能な epoll() 、多くのBSDで利用可能な kqueue() 関数に対するアクセスを提供しています。 Windows 上ではソケットに対してしか動作しないので注意してください; その他のオペレーティングシステムでは、他のファイル形式でも (特に Unixではパイプにも) 動作します。通常のファイルに対して適用し、最後にファイルを読み出した時から内容が増えているかを決定するために使うことはできません。
注釈
selectors モジュールは select モジュールのプリミティブを使って、高水準で効率的な I/O 多重化を実現します。
OS レベルのプリミティブを細かく制御する必要がなければ、代わりに selectors モジュールを使うことをお勧めします。
利用可能な環境: not WASI.
このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは、WebAssembly プラットフォーム を見てください。
このモジュールは以下を定義します:
- select.devpoll()¶
/dev/pollのポーリングオブジェクトを返します。 devpoll オブジェクトが提供するメソッドは、後述の /dev/poll ポーリングオブジェクト 節を参照してください。devpoll()オブジェクトはインスタンス化時に許されるファイル記述子の数にリンクされます。プログラムがこの値を減らす場合devpoll()は失敗します。プログラムがこの値を増やす場合devpoll()は有効なファイル記述子の不完全なリストを返すことがあります。新しいファイル記述子は 継承不可 です。
Added in version 3.3.
バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。
利用可能な環境: Solaris.
- select.epoll(sizehint=-1, flags=0)¶
I/O イベントに対してエッジトリガーまたはレベルトリガーのインターフェースとして使える、エッジポーリングオブジェクトを返します。
sizehint は、登録を見込むイベント数を epoll に伝えます。 正の値、またはデフォルトを使うための
-1でなければなりません。 epoll_create1(2) が利用できない古いシステムでのみ使われ、それ以外では効果がありません (ただし値の検査は行われます)。flags は非推奨で、完全に無視されます。 ただし指定する場合は
0またはselect.EPOLL_CLOEXECでなければならず、それ以外ではOSErrorが送出されます。epoll オブジェクトが提供するメソッドについては、後述の エッジトリガーとレベルトリガーのポーリング (epoll) オブジェクト 節を参照してください。
epollオブジェクトはコンテキストマネジメントプロトコルをサポートしています。with文内で使用された場合、新たなファイル記述子はブロックの最後で自動的に閉じられます。新しいファイル記述子は 継承不可 です。
バージョン 3.3 で変更: flags 引数が追加されました。
バージョン 3.4 で変更:
with文のサポートが追加されました。新しいファイル記述子が継承不可になりました。バージョン 3.4 で非推奨: flags パラメータ。 現在ではデフォルトで
select.EPOLL_CLOEXECが使われます。 ファイルディスクリプタを継承可能にするにはos.set_inheritable()を使ってください。バージョン 3.15 で変更: CPython のビルド時に
--disable-epollを指定すると、この関数を無効にできます。利用可能な環境: Linux >= 2.5.44.
- select.poll()¶
ファイル記述子を登録・登録解除し、それらの I/O イベントをポーリングできるポーリングオブジェクトを返します。 提供されるメソッドは、後述の ポーリングオブジェクト 節を参照してください。
利用可能な環境: Unix.
- select.kqueue()¶
カーネルキューオブジェクトを返します。 kqueue オブジェクトが提供するメソッドは、後述の kqueue オブジェクト 節を参照してください。
新しいファイル記述子は 継承不可 です。
バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。
利用可能な環境: BSD, macOS.
- select.kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)¶
カーネルイベントオブジェクトを返します。 kevent オブジェクトが提供するメソッドは、後述の kevent オブジェクト 節を参照してください。
利用可能な環境: BSD, macOS.
- select.select(rlist, wlist, xlist, timeout=None)¶
Unix の
select()システムコールへの単純なインターフェースです。 最初の三つの引数は「待機可能なオブジェクト」のイテラブルです。 各オブジェクトはファイル記述子を表す整数、または引数なしで呼び出せ、そのような整数を返すfileno()メソッドを持つオブジェクトです。rlist: 読み込み可能になるまで待機
wlist: 書き込み可能になるまで待機
xlist: "例外状態 (exceptional condition)" になるまで待機 ("例外状態" については、システムのマニュアルページを参照してください)
空のイテラブルを渡すこともできますが、三つとも空にできるかどうかはプラットフォームに依存します (Unix では動作し、Windows では動作しないことが知られています)。 省略可能な timeout 引数はタイムアウトを秒単位で指定します。 秒未満の時間を指定するため、整数以外の値も使えます。 timeout 引数を省略するか
Noneにすると、少なくとも一つのファイル記述子が準備完了になるまでブロックします。 ゼロを指定するとポーリングを行い、ブロックしません。戻り値は準備完了状態のオブジェクトからなる 3 つのリストです: したがってこのリストはそれぞれ関数の最初の 3 つの引数のサブセットになります。ファイル記述子のいずれも準備完了にならないままタイムアウトした場合、3 つの空のリストが返されます。
イテラブルの中に含めることのできるオブジェクトは Python ファイルオブジェクト (例えば
sys.stdinや、open()またはos.popen()が返すオブジェクト)、socket.socket()が返すソケットオブジェクトです。 ラッパー <wrapper> クラスを自分で定義することもできます。この場合、適切な (まったくデタラメな数ではなく本物のファイル記述子を返す)fileno()メソッドを持つ必要があります。注釈
Windows ではファイルオブジェクトを使えませんが、ソケットは使えます。 Windows では基盤となる
select()関数が WinSock ライブラリによって提供され、WinSock 以外に由来するファイル記述子を扱えません。バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、
InterruptedErrorを上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 を見てください)。バージョン 3.15 で変更: timeout に、整数や浮動小数点数だけでなく任意の実数を渡せるようになりました。
- select.PIPE_BUF¶
select()、poll()、またはこのモジュールの他のインターフェースがパイプを書き込み可能と報告したときに、ブロックせずに書き込めるバイト数の下限です。 ソケットなど他の種類のファイルに似たオブジェクトには適用されません。この値は POSIX により少なくとも512であることが保証されています。
利用可能な環境: Unix
Added in version 3.2.
/dev/poll ポーリングオブジェクト¶
Solaris とその派生システムには /dev/poll があります。
select() の計算量は O(最大のファイル記述子)、poll() は O(ファイル記述子の数) ですが、/dev/poll は O(アクティブなファイル記述子の数) です。
/dev/poll の動作は標準の poll() オブジェクトによく似ています。
- devpoll.close()¶
ポーリングオブジェクトのファイル記述子を閉じます。
Added in version 3.4.
- devpoll.closed¶
ポーリングオブジェクトが閉じている場合
Trueです。Added in version 3.4.
- devpoll.fileno()¶
ポーリングオブジェクトのファイル記述子番号を返します。
Added in version 3.4.
- devpoll.register(fd[, eventmask])¶
ファイル記述子をポーリングオブジェクトに登録します。これ以降の
poll()メソッド呼び出しでは、そのファイル記述子に処理待ち中の I/O イベントがあるかどうかを監視します。 fd は整数か、整数値を返すfileno()メソッドを持つオブジェクトを取ります。ファイルオブジェクトもfileno()を実装しているので、引数として使うことができます。eventmask は監視するイベントの種類を表す省略可能なビットマスクです。 定数は
poll()オブジェクトと同じです。 デフォルト値はPOLLIN、POLLPRI、POLLOUTの組み合わせです。警告
登録済みのファイル記述子を再び登録してもエラーにはなりませんが、結果は未定義です。 先に登録解除するか、変更するのが適切です。 これは
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 を見てください)。バージョン 3.15 で変更: timeout に、整数や浮動小数点数だけでなく任意の実数を渡せるようになりました。
エッジトリガーとレベルトリガーのポーリング (epoll) オブジェクト¶
https://linux.die.net/man/4/epoll
eventmask は以下の定数を使うビットマスクです。
定数
意味
EPOLLIN読み込み可能。
EPOLLOUT書き込み可能。
EPOLLPRI読み込み可能な緊急データがある。
EPOLLERR対応するファイル記述子でエラーが発生した。
EPOLLHUP対応するファイル記述子でハングアップが発生した。
EPOLLETエッジトリガーの動作に設定する。 デフォルトはレベルトリガー。
EPOLLONESHOT一度だけ通知する動作に設定する。 一つのイベントを取り出すと、そのファイル記述子は内部で無効になる。
EPOLLEXCLUSIVE対応するファイル記述子でイベントが発生したときに、一つの epoll オブジェクトだけの待機を解除します。 デフォルトでは (このフラグを設定しない場合)、そのファイル記述子をポーリングしているすべての epoll オブジェクトの待機を解除します。
EPOLLRDHUPストリームソケットの他端が接続を切断したか、接続の書き込み側のシャットダウンを行った。
EPOLLRDNORM
EPOLLINと同じ
EPOLLRDBAND優先データバンドを読み込める。
EPOLLWRNORM
EPOLLOUTと同じ。
EPOLLWRBAND優先データに書き込みできる。
EPOLLMSG無視される。
EPOLLWAKEUPイベントの待機中にスリープするのを防ぐ。
Added in version 3.6:
EPOLLEXCLUSIVEが追加されました。 Linux カーネル 4.5 以降でのみ利用できます。Added in version 3.14:
EPOLLWAKEUPが追加されました。 Linux カーネル 3.5 以降でのみ利用できます。
- epoll.close()¶
epoll オブジェクトの制御用ファイル記述子を閉じます。
- epoll.closed¶
epoll オブジェクトが閉じている場合 True です。
- epoll.fileno()¶
制御用ファイル記述子の番号を返します。
- epoll.fromfd(fd)¶
fd から epoll オブジェクトを作成します。
- epoll.register(fd[, eventmask])¶
ファイル記述子 fd を epoll オブジェクトに登録します。
- epoll.modify(fd, eventmask)¶
登録済みのファイル記述子 fd を変更します。
- epoll.unregister(fd)¶
epoll オブジェクトから登録されたファイル記述子 fd を削除します。
バージョン 3.9 で変更: このメソッドは
EBADFエラーを無視しなくなりました。
- epoll.poll(timeout=None, maxevents=-1)¶
イベントを待機します。 timeout を指定すると、戻るまでにイベントを待機する時間を秒単位で設定します (整数以外も指定できます)。
バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、
InterruptedErrorを上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 を見てください)。バージョン 3.15 で変更: timeout に、整数や浮動小数点数だけでなく任意の実数を渡せるようになりました。
ポーリングオブジェクト¶
ほとんどの Unix システムで利用できる poll() システムコールは、非常に多数のクライアントに同時にサービスを提供するネットワークサーバーで、より優れたスケーラビリティを発揮します。
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)と同じ効果を持ちます。登録されていないファイル記述子に対してこのメソッドを呼び出すと、 errnoENOENTで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 を見てください)。バージョン 3.15 で変更: timeout に、整数や浮動小数点数だけでなく任意の実数を渡せるようになりました。
ppoll()関数を利用できる場合、timeout の分解能は1ms ではなく1ns (1e-6ms) です。
kqueue オブジェクト¶
- kqueue.close()¶
kqueue オブジェクトの制御用ファイル記述子を閉じる。
- kqueue.closed¶
kqueue オブジェクトが閉じている場合
Trueです。
- kqueue.fileno()¶
制御用ファイル記述子の番号を返します。
- kqueue.fromfd(fd)¶
与えられたファイル記述子から、kqueue オブジェクトを作成する。
- kqueue.control(changelist, max_events[, timeout]) eventlist¶
kevent に対する低水準のインターフェース
changelist は kevent オブジェクトのイテラブルまたは
Nonemax_events は 0 または正の整数
timeoutは秒単位 (整数以外も可) で、デフォルトのNoneでは無期限に待機する
バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、
InterruptedErrorを上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 を見てください)。バージョン 3.15 で変更: timeout に、整数や浮動小数点数だけでなく任意の実数を渡せるようになりました。
kevent オブジェクト¶
https://man.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非同期 I/O 要求。
KQ_FILTER_VNODEReturns when one or more of the requested events watched in fflags occurs.
KQ_FILTER_PROCプロセス ID に対するイベントを監視する。
KQ_FILTER_NETDEVネットワークデバイスに対するイベントを監視する (macOS では利用不可)。
KQ_FILTER_SIGNAL監視しているシグナルがプロセスに届くと返る。
KQ_FILTER_TIMER任意のタイマーを設定する。
- kevent.flags¶
フィルタアクション。
定数
意味
KQ_EV_ADDイベントを追加または変更する。
KQ_EV_DELETEキューからイベントを削除する。
KQ_EV_ENABLEcontrol() がイベントを返すことを許可する。
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ソケットバッファの低水位標 (low water mark)。
KQ_FILTER_VNODEフィルタのフラグ:定数
意味
KQ_NOTE_DELETEunlink() が呼び出された。
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_TRACKfork() 後もプロセスを追跡する。
KQ_NOTE_CHILDNOTE_TRACK に対して子プロセスで返される。
KQ_NOTE_TRACKERR子プロセスに接続できない。
KQ_FILTER_NETDEVフィルタフラグ (macOS では利用不可):定数
意味
KQ_NOTE_LINKUPリンクが有効。
KQ_NOTE_LINKDOWNリンクが無効。
KQ_NOTE_LINKINVリンクの状態が不正。
- kevent.data¶
フィルター固有のデータ。
- kevent.udata¶
ユーザー定義の値。