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 プラットフォーム を見てください。

このモジュールは以下を定義します:

exception select.error

OSError の非推奨のエイリアスです。

バージョン 3.3 で変更: PEP 3151 に基づき、このクラスは OSError のエイリアスになりました。

select.devpoll()

Returns a /dev/poll polling object; see section /dev/poll polling objects below for the methods supported by devpoll objects.

devpoll() オブジェクトはインスタンス化時に許されるファイル記述子の数にリンクされます。プログラムがこの値を減らす場合 devpoll() は失敗します。プログラムがこの値を増やす場合 devpoll() は有効なファイル記述子の不完全なリストを返すことがあります。

新しいファイル記述子は 継承不可 です。

Added in version 3.3.

バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

利用可能な環境: Solaris.

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

Return an edge polling object, which can be used as Edge or Level Triggered interface for I/O events.

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 は非推奨で、完全に無視されます。 ただし指定する場合は 0 または select.EPOLL_CLOEXEC でなければならず、それ以外では OSError が送出されます。

epoll オブジェクトが提供するメソッドについては、後述の Edge and level trigger polling (epoll) objects 節を参照してください。

epoll オブジェクトはコンテキストマネジメントプロトコルをサポートしています。 with 文内で使用された場合、新たなファイル記述子はブロックの最後で自動的に閉じられます。

新しいファイル記述子は 継承不可 です。

バージョン 3.3 で変更: flags 引数が追加されました。

バージョン 3.4 で変更: with 文のサポートが追加されました。新しいファイル記述子が継承不可になりました。

バージョン 3.4 で非推奨: flags パラメータ。 現在ではデフォルトで select.EPOLL_CLOEXEC が使われます。 ファイルディスクリプタを継承可能にするには os.set_inheritable() を使ってください。

利用可能な環境: Linux >= 2.5.44.

select.poll()

Returns a polling object, which supports registering and unregistering file descriptors, and then polling them for I/O events; see section Polling objects below for the methods supported by polling objects.

利用可能な環境: Unix.

select.kqueue()

Returns a kernel queue object; see section Kqueue objects below for the methods supported by kqueue objects.

新しいファイル記述子は 継承不可 です。

バージョン 3.4 で変更: 新しいファイル記述子が継承不可になりました。

利用可能な環境: BSD, macOS.

select.kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)

Returns a kernel event object; see section Kevent objects below for the methods supported by kevent objects.

利用可能な環境: BSD, macOS.

select.select(rlist, wlist, xlist, timeout=None)

Unix の select() システムコールへの単純なインターフェースです。 最初の三つの引数は「待機可能なオブジェクト」のイテラブルです。 各オブジェクトはファイル記述子を表す整数、または引数なしで呼び出せ、そのような整数を返す fileno() メソッドを持つオブジェクトです。

• 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 or None, 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() メソッドを持つ必要があります。

注釈

Windows ではファイルオブジェクトを使えませんが、ソケットは使えます。 Windows では基盤となる select() 関数が WinSock ライブラリによって提供され、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 kinds of file-like objects such as sockets.

この値は POSIX により少なくとも512であることが保証されています。

利用可能な環境: Unix

Added in version 3.2.

/dev/poll polling objects

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 is an optional bitmask describing the type of events you want to check for. The constants are the same as with poll() object. The default value is a combination of the constants POLLIN, POLLPRI, and POLLOUT.

警告

登録済みのファイル記述子を再び登録してもエラーにはなりませんが、結果は未定義です。 先に登録解除するか、変更するのが適切です。 これは poll() との重要な違いです。

devpoll.modify(fd[, eventmask])

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

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 を見てください)。

Edge and level trigger polling (epoll) objects

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

The eventmask is a bit mask using the following constants:

定数	意味
EPOLLIN	Available for read.
EPOLLOUT	Available for write.
EPOLLPRI	Urgent data for read.
EPOLLERR	Error condition happened on the associated fd.
EPOLLHUP	Hang up happened on the associated fd.
EPOLLET	Set Edge Trigger behavior, the default is Level Trigger behavior.
EPOLLONESHOT	Set one-shot behavior. After one event is pulled out, the fd is internally disabled.
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 an fd.
EPOLLRDHUP	ストリームソケットの他端が接続を切断したか、接続の書き込み側のシャットダウンを行った。
EPOLLRDNORM	EPOLLIN と同じ
EPOLLRDBAND	優先データバンドを読み込める。
EPOLLWRNORM	Equivalent to EPOLLOUT.
EPOLLWRBAND	優先データに書き込みできる。
EPOLLMSG	無視される。

Added in version 3.6: EPOLLEXCLUSIVE が追加されました。 Linux カーネル 4.5 以降でのみ利用できます。

epoll.close()

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

epoll.closed

epoll オブジェクトが閉じている場合 True です。

epoll.fileno()

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

epoll.fromfd(fd)

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

epoll.register(fd[, eventmask])

Register a file descriptor fd with the epoll object.

epoll.modify(fd, eventmask)

Modify a registered file descriptor fd.

epoll.unregister(fd)

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

バージョン 3.9 で変更: このメソッドは EBADF エラーを無視しなくなりました。

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

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

バージョン 3.5 で変更: この関数は、シグナルによって中断された時に、 InterruptedError を上げる代わりに再計算されたタイムアウトによってリトライするようになりました。ただし、シグナルハンドラが例外を起こした場合を除きます (この論理的根拠については PEP 475 を見てください)。

Polling objects

ほとんどの 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	There is data to read.
POLLPRI	There is urgent data to read.
POLLOUT	Ready for output: writing will not block.
POLLERR	Error condition of some sort.
POLLHUP	Hung up.
POLLRDHUP	Stream socket peer closed connection, or shut down writing half of connection.
POLLNVAL	Invalid request: descriptor not open.

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

poll.modify(fd, eventmask)

登録されているファイル記述子 fd を変更する。これは、 register(fd, eventmask) と同じ効果を持ちます。登録されていないファイル記述子に対してこのメソッドを呼び出すと、 errno ENOENT で 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 objects

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 objects

https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2

kevent.ident

イベントを特定するための値。この値は、フィルタにもよりますが、大抵の場合はファイル記述子です。コンストラクタでは、 ident として、整数値か fileno() メソッドを持ったオブジェクトを渡せます。 kevent は内部で整数値を保存します。

kevent.filter

カーネルフィルタの名前。

定数	意味
KQ_FILTER_READ	Takes a descriptor and returns whenever there is data available to read.
KQ_FILTER_WRITE	Takes a descriptor and returns whenever there is data available to write.
KQ_FILTER_AIO	AIO requests.
KQ_FILTER_VNODE	Returns when one or more of the requested events watched in fflag occurs.
KQ_FILTER_PROC	Watch for events on a process ID.
KQ_FILTER_NETDEV	Watch for events on a network device (not available on macOS).
KQ_FILTER_SIGNAL	Returns whenever the watched signal is delivered to the process.
KQ_FILTER_TIMER	Establishes an arbitrary timer.

kevent.flags

フィルタアクション。

定数	意味
KQ_EV_ADD	Adds or modifies an event.
KQ_EV_DELETE	Removes an event from the queue.
KQ_EV_ENABLE	Permits control() to return the event.
KQ_EV_DISABLE	Disables event.
KQ_EV_ONESHOT	Removes event after first occurrence.
KQ_EV_CLEAR	Reset the state after an event is retrieved.
KQ_EV_SYSFLAGS	Internal event.
KQ_EV_FLAG1	Internal event.
KQ_EV_EOF	Filter-specific EOF condition.
KQ_EV_ERROR	See return values.

kevent.fflags

Filter-specific flags.

KQ_FILTER_READ と KQ_FILTER_WRITE フィルタのフラグ:

定数	意味
KQ_NOTE_LOWAT	Low water mark of a socket buffer.

KQ_FILTER_VNODE フィルタのフラグ:

定数	意味
KQ_NOTE_DELETE	unlink() was called.
KQ_NOTE_WRITE	A write occurred.
KQ_NOTE_EXTEND	The file was extended.
KQ_NOTE_ATTRIB	An attribute was changed.
KQ_NOTE_LINK	The link count has changed.
KQ_NOTE_RENAME	The file was renamed.
KQ_NOTE_REVOKE	Access to the file was revoked.

KQ_FILTER_PROC フィルタフラグ:

定数	意味
KQ_NOTE_EXIT	The process has exited.
KQ_NOTE_FORK	The process has called fork().
KQ_NOTE_EXEC	The process has executed a new process.
KQ_NOTE_PCTRLMASK	Internal filter flag.
KQ_NOTE_PDATAMASK	Internal filter flag.
KQ_NOTE_TRACK	Follow a process across fork().
KQ_NOTE_CHILD	Returned on the child process for NOTE_TRACK.
KQ_NOTE_TRACKERR	Unable to attach to a child.

KQ_FILTER_NETDEV フィルタフラグ (macOS では利用不可):

定数	意味
KQ_NOTE_LINKUP	Link is up.
KQ_NOTE_LINKDOWN	Link is down.
KQ_NOTE_LINKINV	Link state is invalid.

kevent.data

Filter-specific data.

kevent.udata

User-defined value.