:mod:`uselect` -- 在一组流中等待事件
========================================================================

.. module:: uselect
   :synopsis: 在一组流中等待事件

该模块实现相应 `CPython` 模块的子集，如下所示。更多信息，请参见

|see_cpython_module| :mod:`python:select`.

该模块提供用以在流中等待事件的函数（选择用于操作的流）。

函数
---------

.. function:: poll()

   创建轮询类的实例。

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

   等待一组对象上的活动。

   这个函数为兼容性设计，效率不高。建议使用 ``Poll`` 。

.. _class: Poll

``Poll`` 类
--------------

方法
~~~~~~~

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

   注册用于轮询的 ``obj`` 。 ``eventmask`` 是下列的逻辑或：

   * ``select.POLLIN``  - 用于读取的数据
   * ``select.POLLOUT`` - 可写入更多数据

   请注意，像 ``uselect.POLLHUP`` 和 ``uselect.POLLERR`` 这样的标志作为输入事件掩码是 *无效* 的
   （这些是未经请求的事件，无论是否被请求，都将从 `poll()` 返回）。此语义符合 POSIX。

   *eventmask* 默认值为 ``select.POLLIN | select.POLLOUT``.
   
   对于同一个 *obj* ，可以多次调用这个函数。
   连续调用会将 *obj* 的事件掩码更新为 *eventmask* 的值(也就是说，将表现为 `modify()` )。
   
.. method:: poll.unregister(obj)

   注销轮询的 *obj* 。

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

   修改 *obj* 的 *eventmask* 。如果 *obj* 没有被注册，则会引发 `OSError` ，并显示ENOENT错误。

.. method:: poll.poll(timeout=-1)

   等待至少一个已注册的对象准备就绪或处于异常状态，并带有以毫秒为单位的可选超时(以毫秒为单位)(如果 *timeout* 未指定或为-1，则不存在超时)。
   
   返回( ``obj`` , ``event`` , ...)的元组列表。元组中可能还有其他元素，具体取决于平台和版本，因此请不要假定其大小为2。
   ``event`` event元素指定流中发生了哪些事件，并且是上述 ``uselect.POLL*`` 常量的组合。
   注意标记 ``uselect.POLLHUP`` 和 ``uselect.POLLERR`` 可以在任何时候返回(即使没有被请求)，
   并且必须对其进行相应的操作(相应的流已从轮询中注销并可能已关闭)，因为否则所有对 `poll()` 的进一步调用都可能立即返回，并再次为此流设置这些标志。

   如果超时，则返回一个空列表。


   .. admonition:: 与CPython区别
      :class: attention

      如上所述，返回的元组可能包括多于2个元素。

.. method:: poll.ipoll(timeout=-1, flags=0)

   与 :meth:`poll.poll` 类似，但是返回一个产生被调用函数所有元组的迭代器。该函数提供高效的、无位置的在流中进行轮询的方法。

   如果 *flags* 为1，则采用事件的一次性行为：发生事件的流将自动重置其事件掩码(相当于 ``poll.modify(obj, 0)`` )，
   因此针对此类事件的新事件在使用 `poll.modify()` 设置新的掩码之前，流将不会被处理。此行为对于异步I/O调度程序很有用。

   .. admonition:: 与CPython区别
      :class: attention

      该函数是MicroPython的扩展。