
:mod:`select` --- I/O 処理の完了を待機する
==========================================

.. module:: select
   :synopsis: 複数のストリームに対してI/O 処理の完了を待機します。


このモジュールでは、ほとんどのオペレーティングシステムで利用可能な :cfunc:`select` および :cfunc:`poll` 関数、
Linux 2.5+ で利用可能な :cfunc:`epoll`, 多くのBSDで利用可能な :cfunc:`kqueue` 関数に対するアクセスを提供しています。
Windows の上ではソケットに対してしか動作しないので注意してください; その他のオペレーティングシステムでは、他のファイル形式でも
(特に Unixではパイプにも) 動作します。通常のファイルに対して適用し、最後にファイルを読み出した時から内容が増えているかを
決定するために使うことはできません。

このモジュールでは以下の内容を定義しています:


.. exception:: error

   エラーが発生したときに送出される例外です。エラーに付属する値は、 :cdata:`errno` からとったエラーコードを表す数値とその
   エラーコードに対応する文字列からなるペアで、C 関数の :cfunc:`perror` が出力するものと同様です。


.. function:: epoll([sizehint=-1])

   .. (Only supported on Linux 2.5.44 and newer.)  Returns an edge polling object,
      which can be used as Edge or Level Triggered interface for I/O events; see
      section :ref:`epoll-objects` below for the methods supported by epolling
      objects.

   (Linux 2.5.44 以降でのみサポート) エッジポーリング(edge polling)オブジェクトを返します。
   このオブジェクトは、 I/O イベントのエッジトリガもしくはレベルトリガインタフェースとして使うことができます。
   エッジポーリングオブジェクトのメソッドについては、 :ref:`epoll-objects` 節を参照してください。

   .. versionadded:: 2.6


.. function:: poll()

   (全てのオペレーティングシステムでサポートされているわけではありません。) ポーリングオブジェクトを返します。このオブジェクトは
   ファイル記述子を登録したり登録解除したりすることができ、ファイル記述子に対する I/O イベント発生をポーリングすることができます;
   ポーリングオブジェクトが提供しているメソッドについては下記の  :ref:`poll-objects` 節を参照してください。


.. function:: kqueue()

   .. (Only supported on BSD.)  Returns a kernel queue object object; see section
      :ref:`kqueue-objects` below for the methods supported by kqueue objects.

   (BSD でのみサポート) カーネルキュー(kernel queue)オブジェクトを返します。
   カーネルキューオブジェクトがサポートしているメソッドについては、下の
   :ref:`kqueue-objects` 節を参照してください。

   .. versionadded:: 2.6


.. function:: kevent(ident, filter=KQ_FILTER_READ, flags=KQ_ADD, fflags=0, data=0, udata=0)

   .. (Only supported on BSD.)  Returns a kernel event object object; see section
      :ref:`kevent-objects` below for the methods supported by kqueue objects.

   (BSD でのみサポート) カーネルイベント(kernel event)オブジェクトを返します。
   このオブジェクトのメソッドについては、下の :ref:`kevent-objects` 節を参照してください。

   .. versionadded:: 2.6


.. function:: select(rlist, wlist, xlist[, timeout])

   Unix の :cfunc:`select` システムコールに対する直接的なインタフェースです。
   最初の 3 つの引数は '待機可能なオブジェクト'
   からなるシーケンスです: ファイル記述子を表す整数値、または引数を持たず、整数を返すメソッド :meth:`fileno` を持つ
   オブジェクトです。

   * *rlist*: 読み込み可能になるまで待つ
   * *wlist*: 書き込み可能になるまで待つ
   * *xlist*: "例外状態 (exceptional condition)" になるまで待つ("例外状態" については、
     システムのmanual pageを参照してください)

   いずれかに空のシーケンスを指定してもかまいませんが、3 つ全てを空のシーケンスにしてもよいかどうかはプラットフォームに依存します (Unix では動作し、Windows では
   動作しないことが知られています)。
   オプションの *timeout* 引数にはタイムアウトまでの秒数を浮動小数点数型で指定します。 *timeout*
   引数が省略された場合、関数は少なくとも一つのファイル記述子が何らかの準備完了状態になるまでブロックします。
   *timeout* に 0 を指定した場合は、ポーリングを行いブロックしないことを示します。

   戻り値は準備完了状態のオブジェクトからなる 3 つのリストです: 従ってこのリストはそれぞれ関数の最初の 3 つの引数のサブセットに
   なります。ファイル記述子のいずれも準備完了にならないままタイムアウトした場合、3 つの空のリストが返されます。

   .. index::
      single: socket() (in module socket)
      single: popen() (in module os)

   シーケンスの中に含めることのできるオブジェクトは Python ファイルオブジェクト (すなわち ``sys.stdin``, あるいは
   :func:`open` や :func:`os.popen` が返すオブジェクト)、 :func:`socket.socket` が返すソケットオブジェクト
   です。 :dfn:`wrapper` クラスを自分で定義することもできます。この場合、適切な
   (単なる乱数ではなく本当のファイル記述子を返す) :meth:`fileno`  メソッドを持つ必要があります

   .. note::

      .. index:: single: WinSock

      :func:`select` はWindows のファイルオブジェクトを受理しませんが、ソケットは受理します。
      Windows では、背後の :cfunc:`select` 関数は WinSock ライブラリで提供されており、
      WinSock によって生成されたものではないファイル記述子を扱うことができないのです。


.. _epoll-objects:

.. Edge and Level Trigger Polling (epoll) Objects

エッジとレベルトリガのポーリング(epoll)オブジェクト
---------------------------------------------------

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

   *eventmask*

   +-----------------------+-----------------------------------------------+
   | 定数i                 | 意味                                          |
   +=======================+===============================================+
   | :const:`EPOLLIN`      | 読み込み可能                                  |
   +-----------------------+-----------------------------------------------+
   | :const:`EPOLLOUT`     | 書き込み可能                                  |
   +-----------------------+-----------------------------------------------+
   | :const:`EPOLLPRI`     | 緊急の読み出しデータの存在                    |
   +-----------------------+-----------------------------------------------+
   | :const:`EPOLLERR`     | 設定された fd にエラー状態が発生した          |
   +-----------------------+-----------------------------------------------+
   | :const:`EPOLLHUP`     | 設定された fd がハングアップした              |
   +-----------------------+-----------------------------------------------+
   | :const:`EPOLLET`      | エッジトリガ動作に設定する。デフォルトでは    |
   |                       | レベルトリガ動作                              |
   +-----------------------+-----------------------------------------------+
   | :const:`EPOLLONESHOT` | 1ショット動作に設定する。1回イベントが取り出  |
   |                       | されたら、その fd が内部で無効になる。        |
   +-----------------------+-----------------------------------------------+
   | :const:`EPOLLRDNORM`  | ???                                           |
   +-----------------------+-----------------------------------------------+
   | :const:`EPOLLRDBAND`  | ???                                           |
   +-----------------------+-----------------------------------------------+
   | :const:`EPOLLWRNORM`  | ???                                           |
   +-----------------------+-----------------------------------------------+
   | :const:`EPOLLWRBAND`  | ???                                           |
   +-----------------------+-----------------------------------------------+
   | :const:`EPOLLMSG`     | ???                                           |
   +-----------------------+-----------------------------------------------+


.. method:: epoll.close()

   .. Close the control file descriptor of the epoll object.

   epoll オブジェクトの制御用ファイルディスクリプタを閉じる


.. method:: epoll.fileno()

   .. Return the file descriptor number of the control fd.

   制御用ファイルディスクリプタの番号を返す


.. method:: epoll.fromfd(fd)

   .. Create an epoll object from a given file descriptor.

   *fd* から epoll オブジェクトを作成する


.. method:: epoll.register(fd[, eventmask])

   .. Register a fd descriptor with the epoll object.

   epoll オブジェクトにファイルディスクリプタ *fd* を登録する


.. method:: epoll.modify(fd, eventmask)

   .. Modify a register file descriptor.

   ファイルディスクリプタ *fd* の登録を変更する


.. method:: epoll.unregister(fd)

   .. Remove a registered file descriptor from the epoll object.

   epoll オブジェクトから登録されたファイルディスクリプタ *fd* を削除する


.. method:: epoll.poll([timeout=-1[, maxevents=-1]])

   .. Wait for events. timeout in seconds (float)

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


.. _poll-objects:

ポーリングオブジェクト
----------------------

:cfunc:`poll` システムコールはほとんどの Unix システムでサポートされており、非常に多数のクライアントに同時にサービスを提供するような
ネットワークサーバが高い拡張性を持てるようにしています。 :cfunc:`poll` に高い拡張性があるのは、 :cfunc:`select` が
ビット対応表を構築し、対象ファイルの記述子に対応するビットを立て、その後全ての対応表の全てのビットを線形探索するのに対し、 :cfunc:`poll`
は対象のファイル記述子を列挙するだけでよいからです。 :cfunc:`select` は O(最大のファイル記述子番号) なのに対し、
:cfunc:`poll` は O(対象とするファイル記述子の数) で済みます。


.. method:: poll.register(fd[, eventmask])

   ファイル記述子をポーリングオブジェクトに登録します。これ以降の :meth:`poll` メソッド呼び出しでは、そのファイル記述子に処理待ち中の I/O
   イベントがあるかどうかを監視します。 *fd* は整数か、整数値を返す :meth:`fileno` メソッドを持つオブジェクトを取ります。
   ファイルオブジェクトも通常 :meth:`fileno` を実装しているので、引数として使うことができます。

   *eventmask* はオプションのビットマスクで、どのタイプの I/O イベントを監視したいかを記述します。この値は以下の表で述べる定数
   :const:`POLLIN` 、 :const:`POLLPRI` 、および :const:`POLLOUT` の組み合わせにすることが
   できます。ビットマスクを指定しない場合、標準の値が使われ、 3 種のイベント全てに対して監視が行われます。

   +-------------------+----------------------------------------------------------+
   | 定数              | 意味                                                     |
   +===================+==========================================================+
   | :const:`POLLIN`   | 読み出せるデータの存在                                   |
   +-------------------+----------------------------------------------------------+
   | :const:`POLLPRI`  | 緊急の読み出しデータの存在                               |
   +-------------------+----------------------------------------------------------+
   | :const:`POLLOUT`  | 書き出せるかどうか: 書き出し処理がブロックしないかどうか |
   +-------------------+----------------------------------------------------------+
   | :const:`POLLERR`  | 何らかのエラー状態                                       |
   +-------------------+----------------------------------------------------------+
   | :const:`POLLHUP`  | ハングアップ                                             |
   +-------------------+----------------------------------------------------------+
   | :const:`POLLNVAL` | 無効な要求: 記述子が開かれていない                       |
   +-------------------+----------------------------------------------------------+

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


.. method:: poll.modify(fd, eventmask)

   .. Modifies an already registered fd. This has the same effect as
      :meth:`register(fd, eventmask)`.  Attempting to modify a file descriptor
      that was never registered causes an :exc:`IOError` exception with errno
      :const:`ENOENT` to be raised.

   登録されているファイルディスクリプタ *fd* を変更する。
   これは、 :meth:`register(fd, eventmask)` と同じ効果を持つ。
   登録されていないファイルディスクリプタに対してこのメソッドを呼びだすと、
   errno が :const:`ENOENT` の :exc:`IOError` 例外が送出します。

   .. versionadded:: 2.6


.. method:: poll.unregister(fd)

   ポーリングオブジェクトによって追跡中のファイル記述子を登録解除します。 :meth:`register` メソッドと同様に、 *fd* は整数か、整数値を返す
   :meth:`fileno` メソッドを持つオブジェクトを取ります。

   登録されていないファイル記述子を登録解除しようとすると :exc:`KeyError` 例外が送出されます。


.. method:: poll.poll([timeout])

   登録されたファイル記述子に対してポーリングを行い、報告すべき I/O イベントまたはエラーの発生したファイル記述子に毎に 2 要素のタプル ``(fd,
   event)`` からなるリストを返します。リストは空になることもあります。 *fd* はファイル記述子で、 *event* は該当するファイル記述子
   について報告されたイベントを表すビットマスクです --- 例えば :const:`POLLIN` は入力待ちを示し、 :const:`POLLOUT`
   はファイル記述子に対する書き込みが可能を示す、などです。空のリストは呼び出しがタイムアウトしたか、報告すべきイベントが
   どのファイル記述子でも発生しなかったことを示します。 *timeout* が与えられた場合、処理を戻すまで待機する時間の長さを
   ミリ秒単位で指定します。 *timeout* が省略されたり、負の値であったり、あるいは :const:`None`
   の場合、そのポーリングオブジェクトが監視している何らかのイベントが発生するまでブロックします。


.. _kqueue-objects:

kqueue オブジェクト
-------------------

.. method:: kqueue.close()

   .. Close the control file descriptor of the kqueue object.

   kqueue オブジェクトの制御用ファイルディスクリプタを閉じる


.. method:: kqueue.fileno()

   .. Return the file descriptor number of the control fd.

   制御用ファイルディスクリプタの番号を返す


.. method:: kqueue.fromfd(fd)

   .. Create a kqueue object from a given file descriptor.

   与えられたファイルディスクリプタから、kqueue オブジェクトを作成する


.. method:: kqueue.control(changelist, max_events[, timeout=None]) -> eventlist

   .. Low level interface to kevent

   kevent に対する低レベルのインタフェース

   .. - changelist must be an iterable of kevent object or None
      - max_events must be 0 or a positive integer
      - timeout in seconds (floats possible)

   - *changelist* は kevent オブジェクトのイテレータブルか、 ``None``
   - *max_events* は 0 か正の整数
   - *timeout* タイムアウト秒数(floatを利用可能)


.. _kevent-objects:

.. Kevent Objects

kevent オブジェクト
--------------------

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

.. attribute:: kevent.ident

   .. Value used to identify the event. The interpretation depends on the filter
      but it's usually the file descriptor. In the constructor ident can either
      be an int or an object with a fileno() function. kevent stores the integer
      internally.

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


.. attribute:: kevent.filter

   .. Name of the kernel filter

   kernel filter の名前

   +---------------------------+--------------------------------------------------------------------------+
   | 定数                      | 意味                                                                     |
   +===========================+==========================================================================+
   | :const:`KQ_FILTER_READ`   | ディスクリプタを受け取り、読み込めるデータが存在する時に戻る             |
   +---------------------------+--------------------------------------------------------------------------+
   | :const:`KQ_FILTER_WRITE`  | ディスクリプタを受け取り、書き込み可能な時に戻る                         |
   +---------------------------+--------------------------------------------------------------------------+
   | :const:`KQ_FILTER_AIO`    | AIO リクエスト                                                           |
   +---------------------------+--------------------------------------------------------------------------+
   | :const:`KQ_FILTER_VNODE`  | *fflag* で監視されたイベントが1つ以上発生したときに戻る                  |
   +---------------------------+--------------------------------------------------------------------------+
   | :const:`KQ_FILTER_PROC`   | プロセスID上のイベントを監視する                                         |
   +---------------------------+--------------------------------------------------------------------------+
   | :const:`KQ_FILTER_NETDEV` | ネットワークデバイス上のイベントを監視する (Mac OS X では利用不可)       |
   +---------------------------+--------------------------------------------------------------------------+
   | :const:`KQ_FILTER_SIGNAL` | 監視しているシグナルがプロセスに届いたときに戻る                         |
   +---------------------------+--------------------------------------------------------------------------+
   | :const:`KQ_FILTER_TIMER`  | 任意のタイマを設定します                                                 |
   +---------------------------+--------------------------------------------------------------------------+

.. attribute:: kevent.flags

   .. Filter action

   フィルタ・アクション

   +---------------------------+---------------------------------------------+
   | 定数                      | 意味                                        |
   +===========================+=============================================+
   | :const:`KQ_EV_ADD`        | イベントを追加したり修正する                |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_DELETE`     | キューからイベントを取り除く                |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_ENABLE`     | control()がイベントを返すのを許可する       |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_DISABLE`    | イベントを無効にする                        |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_ONESHOT`    | イベントを最初の発生後無効にする            |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_CLEAR`      | イベントを受け取った後状態をリセットする    |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_SYSFLAGS`   | 内部イベント                                |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_FLAG1`      | 内部イベント                                |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_EOF`        | フィルタ依存のEOF状態                       |
   +---------------------------+---------------------------------------------+
   | :const:`KQ_EV_ERROR`      | 戻り値を参照                                |
   +---------------------------+---------------------------------------------+


.. attribute:: kevent.fflags

   .. Filter specific flags

   フィルタ依存のフラグ


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

   +----------------------------+--------------------------------------------+
   | 定数                       | 意味                                       |
   +============================+============================================+
   | :const:`KQ_NOTE_LOWAT`     | ソケットバッファの最低基準値               |
   +----------------------------+--------------------------------------------+


   :const:`KQ_FILTER_VNODE` フィルタのフラグ

   +----------------------------+--------------------------------------------+
   | 定数                       | 意味                                       |
   +============================+============================================+
   | :const:`KQ_NOTE_DELETE`    | *unlink()* が呼ばれた                      |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_WRITE`     | 書き込みが発生した                         |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_EXTEND`    | ファイルのサイズが拡張された               |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_ATTRIB`    | 属性が変更された                           |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_LINK`      | リンクカウントが変更された                 |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_RENAME`    | ファイル名が変更された                     |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_REVOKE`    | ファイルアクセスがrevokeされた             |
   +----------------------------+--------------------------------------------+


   :const:`KQ_FILTER_PROC` フィルタフラグ

   +----------------------------+---------------------------------------------------+
   | 定数                       | 意味                                              |
   +============================+===================================================+
   | :const:`KQ_NOTE_EXIT`      | プロセスが終了した                                |
   +----------------------------+---------------------------------------------------+
   | :const:`KQ_NOTE_FORK`      | プロセスで *fork()* が呼ばれた                    |
   +----------------------------+---------------------------------------------------+
   | :const:`KQ_NOTE_EXEC`      | プロセスが新しいプロセスを実行した                |
   +----------------------------+---------------------------------------------------+
   | :const:`KQ_NOTE_PCTRLMASK` | 内部フィルタフラグ                                |
   +----------------------------+---------------------------------------------------+
   | :const:`KQ_NOTE_PDATAMASK` | 内部フィルタフラグ                                |
   +----------------------------+---------------------------------------------------+
   | :const:`KQ_NOTE_TRACK`     | *fork()* の呼び出しを超えてプロセスを監視します   |
   +----------------------------+---------------------------------------------------+
   | :const:`KQ_NOTE_CHILD`     | *NOTE_TRACK* で子プロセスに渡されます             |
   +----------------------------+---------------------------------------------------+
   | :const:`KQ_NOTE_TRACKERR`  | 子プロセスにアタッチできなかった                  |
   +----------------------------+---------------------------------------------------+

   :const:`KQ_FILTER_NETDEV` フィルタフラグ [Mac OS X では利用不可]

   +----------------------------+--------------------------------------------+
   | 定数                       | 意味                                       |
   +============================+============================================+
   | :const:`KQ_NOTE_LINKUP`    | リンクアップしている                       |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_LINKDOWN`  | リンクダウンしている                       |
   +----------------------------+--------------------------------------------+
   | :const:`KQ_NOTE_LINKINV`   | リンク状態が不正                           |
   +----------------------------+--------------------------------------------+


.. attribute:: kevent.data

   .. Filter specific data

   フィルタ固有のデータ


.. attribute:: kevent.udata

   .. User defined value

   ユーザー定義値
