select
--- I/O 完了の待機¶
このモジュールでは、ほとんどのオペレーティングシステムで利用可能な select()
および poll()
関数、Solaris やその派生で利用可能な devpoll()
、Linux 2.5+ で利用可能な epoll()
、多くのBSDで利用可能な kqueue()
関数に対するアクセスを提供しています。 Windows 上ではソケットに対してしか動作しないので注意してください; その他のオペレーティングシステムでは、他のファイル形式でも (特に Unixではパイプにも) 動作します。通常のファイルに対して適用し、最後にファイルを読み出した時から内容が増えているかを決定するために使うことはできません。
注釈
selectors
モジュールにより、select
モジュールプリミティブに基づく高水準かつ効率的な I/O の多重化が行うことが出来ます。
OS レベルプリミティブを使用した正確な制御を求めない限り、代わりに selectors
を使用することが推奨されます。
Availability: not Emscripten, not WASI.
This module does not work or is not available on WebAssembly platforms
wasm32-emscripten
and wasm32-wasi
. See
WebAssembly プラットフォーム for more information.
このモジュールは以下を定義します:
- select.devpoll()¶
(Solaris およびその派生でのみサポートされています)
/dev/poll
ポーリングオブジェクトを返します。 ポーリングオブジェクトが提供しているメソッドについては ポーリングオブジェクト 節を参照してください。devpoll()
オブジェクトはインスタンス化時に許されるファイル記述子の数にリンクされます。プログラムがこの値を減らす場合devpoll()
は失敗します。プログラムがこの値を増やす場合devpoll()
は有効なファイル記述子の不完全なリストを返すことがあります。新しいファイル記述子は 継承不可 です。
Added in version 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 whereepoll_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
orselect.EPOLL_CLOEXEC
, otherwiseOSError
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])¶
This is a straightforward interface to the Unix
select()
system call. The first three arguments are iterables of 'waitable objects': either integers representing file descriptors or objects with a parameterless method namedfileno()
returning such an integer:rlist: 読み込み可能になるまで待機
wlist: 書き込み可能になるまで待機
xlist: "例外状態 (exceptional condition)" になるまで待機 ("例外状態" については、システムのマニュアルページを参照してください)
Empty iterables are allowed, but acceptance of three empty iterables is platform-dependent. (It is known to work on Unix but not on Windows.) The optional timeout argument specifies a time-out as a floating-point number in seconds. When the timeout argument is omitted the function blocks until at least one file descriptor is ready. A time-out value of zero specifies a poll and never blocks.
戻り値は準備完了状態のオブジェクトからなる 3 つのリストです: したがってこのリストはそれぞれ関数の最初の 3 つの引数のサブセットになります。ファイル記述子のいずれも準備完了にならないままタイムアウトした場合、3 つの空のリストが返されます。
イテラブルの中に含めることのできるオブジェクトは Python ファイルオブジェクト (例えば
sys.stdin
や、open()
またはos.popen()
が返すオブジェクト)、socket.socket()
が返すソケットオブジェクトです。 ラッパー <wrapper> クラスを自分で定義することもできます。この場合、適切な (まったくデタラメな数ではなく本物のファイル記述子を返す)fileno()
メソッドを持つ必要があります。注釈
File objects on Windows are not acceptable, but sockets are. On Windows, the underlying
select()
function is provided by the WinSock library, and does not handle file descriptors that don't originate from WinSock.バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、
InterruptedError
を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 を見てください)。
- 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.この値は POSIX により少なくとも512であることが保証されています。
利用可能な環境: Unix
Added in version 3.2.
/dev/poll
ポーリングオブジェクト¶
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()¶
ポーリングオブジェクトのファイル記述子を閉じます。
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 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 constantsPOLLIN
,POLLPRI
, andPOLLOUT
.警告
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])¶
このメソッドは
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
無視される。
Added in version 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 を見てください)。
ポーリングオブジェクト¶
The poll()
system call, supported on most Unix systems, provides better
scalability for network servers that service many, many clients at the same
time. poll()
scales better because the system call only requires listing
the file descriptors of interest, while select()
builds a bitmap, turns
on bits for the fds of interest, and then afterward the whole bitmap has to be
linearly scanned again. select()
is O(highest file descriptor), while
poll()
is O(number of file descriptors).
- 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 を見てください)。
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://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
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¶
ユーザー定義値。