"select" --- 等待 I/O 完成
**************************

======================================================================

该模块提供了对 "select()" 和 "poll()" 函数的访问，这些函数在大多数操作
系统中是可用的。在 Solaris 及其衍生版本上可用 "devpoll()"，在 Linux
2.5+ 上可用 "epoll()"，在大多数 BSD 上可用 "kqueue()"。注意，在
Windows 上，本模块仅适用于套接字；在其他操作系统上，本模块也适用于其他
文件类型（特别地，在 Unix 上也适用于管道）。本模块不能用于常规文件，不
能检测出（自上次读取文件后）文件是否有新数据写入。

備註:

  "selectors" 模块是在 "select" 模块原型的基础上进行高级且高效的 I/O
  复用。推荐用户改用 "selectors" 模块，除非用户希望对 OS 级的函数原型
  进行精确控制。

该模块定义以下内容：

exception select.error

   一个被弃用的 "OSError" 的别名。

   3.3 版更變: 根据 **PEP 3151**，这个类是 "OSError" 的别名。

select.devpoll()

   （仅支持 Solaris 及其衍生版本）返回一个 "/dev/poll" 轮询对象，请参
   阅下方 /dev/poll 轮询对象 获取 devpoll 对象所支持的方法。

   "devpoll()" 对象与实例化时允许的文件描述符数量有关，如果在程序中降
   低了此数值，"devpoll()" 调用将失败。如果程序提高了此数值，
   "devpoll()" 可能会返回一个不完整的活动文件描述符列表。

   新的文件描述符是 不可继承的。

   3.3 版新加入.

   3.4 版更變: 新的文件描述符现在是不可继承的。

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

   （仅支持 Linux 2.5.44 或更高版本）返回一个 edge poll 对象，该对象可
   作为 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 where "epoll_create1()" is not
   available; otherwise it has no effect (though its value is still
   checked).

   *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()" 来让文件描述符可继承。

select.poll()

   （部分操作系统不支持）返回一个 poll 对象，该对象支持注册和注销文件
   描述符，支持对描述符进行轮询以获取 I/O 事件。请参阅下方 Poll 对象
   获取 poll 对象所支持的方法。

select.kqueue()

   （仅支持 BSD）返回一个内核队列对象，请参阅下方 Kqueue 对象 获取
   kqueue 对象所支持的方法。

   新的文件描述符是 不可继承的。

   3.4 版更變: 新的文件描述符现在是不可继承的。

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

   （仅支持 BSD）返回一个内核事件对象，请参阅下方 Kevent 对象 获取
   kevent 对象所支持的方法。

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

   这是一个明白直观的 Unix "select()" 系统调用接口。 前三个参数是由‘可
   等待对象’组成的序列：可以是代表文件描述符的整数，或是带有名为
   "fileno()" 的返回这样的整数的无形参方法的对象:

   * *rlist*：等待，直到可以开始读取

   * *wlist*：等待，直到可以开始写入

   * *xlist*：等待“异常情况”（请参阅当前系统的手册，以获取哪些情况称为
     异常情况）

   允许空的可迭代对象，但是否接受三个空的可迭代对象则取决于具体平台。
   （已知在 Unix 上可行但在 Windows 上不可行。） 可选的 *timeout* 参数
   以一个浮点数表示超时秒数。 当省略 *timeout* 参数时该函数将阻塞直到
   至少有一个文件描述符准备就绪。 超时值为零表示执行轮询且永不阻塞。

   返回值是三个列表，包含已就绪对象，返回的三个列表是前三个参数的子集
   。当超时时间已到且没有文件描述符就绪时，返回三个空列表。

   可迭代对象中可接受的对象类型有 Python *文件对象* (例如 "sys.stdin"
   以及 "open()" 或 "os.popen()" 所返回的对象)，由 "socket.socket()"
   返回的套接字对象等。 你也可以自定义一个 *wrapper* 类，只要它具有适
   当的 "fileno()" 方法（该方法要确实返回一个文件描述符，而不能只是一
   个随机整数）。

   備註:

     Windows 上不接受文件对象，但接受套接字。在 Windows 上，底层的
     "select()" 函数由 WinSock 库提供，且不处理不是源自 WinSock 的文件
     描述符。

   3.5 版更變: 现在，当本函数被信号中断时，重试超时将从头开始计时，不
   会抛出 "InterruptedError" 异常。除非信号处理程序抛出异常（相关原理
   请参阅 **PEP 475**）。

select.PIPE_BUF

   当一个管道已经被 "select()"、"poll()" 或本模块中的某个接口报告为可
   写入时，可以在不阻塞该管道的情况下写入的最小字节数。它不适用于套接
   字等其他类型的文件类对象。

   POSIX 上须保证该值不小于 512。

   適用：Unix。

   3.2 版新加入.


"/dev/poll" 轮询对象
====================

Solaris 及其衍生版本具备 "/dev/poll"。"select()" 复杂度为 O（最高文件
描述符），"poll()" 为 O（文件描述符数量），而 "/dev/poll" 为 O（活动的
文件描述符）。

"/dev/poll" 的行为与标准 "poll()" 对象十分类似。

devpoll.close()

   关闭轮询对象的文件描述符。

   3.4 版新加入.

devpoll.closed

   如果轮询对象已关闭，则返回 "True"。

   3.4 版新加入.

devpoll.fileno()

   返回轮询对象的文件描述符对应的数字。

   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])

   轮询已注册的文件描述符的集合，并返回一个列表，列表可能为空，也可能
   有多个 "(fd, event)" 2元组，其中包含了要报告事件或错误的描述符。
   *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"                | 在关联的文件描述符上有错误情况发生              |
   +---------------------------+-------------------------------------------------+
   | "EPOLLHUP"                | 关联的文件描述符已挂起                          |
   +---------------------------+-------------------------------------------------+
   | "EPOLLET"                 | 设置触发方式为边缘触发，默认为水平触发          |
   +---------------------------+-------------------------------------------------+
   | "EPOLLONESHOT"            | 设置 one-shot 模式。触发一次事件后，该描述符会  |
   |                           | 在轮询对象内部被禁用 。                         |
   +---------------------------+-------------------------------------------------+
   | "EPOLLEXCLUSIVE"          | 当已关联的描述符发生事件时，仅唤醒一个 epoll 对 |
   |                           | 象。默认（如果未设置 此标志）是唤醒所有轮询该描 |
   |                           | 述符的 epoll 对象。                             |
   +---------------------------+-------------------------------------------------+
   | "EPOLLRDHUP"              | 流套接字的对侧关闭了连接或关闭了写入到一半的连  |
   |                           | 接。                                            |
   +---------------------------+-------------------------------------------------+
   | "EPOLLRDNORM"             | 等價於 "EPOLLIN"                                |
   +---------------------------+-------------------------------------------------+
   | "EPOLLRDBAND"             | 可以读取优先数据带。                            |
   +---------------------------+-------------------------------------------------+
   | "EPOLLWRNORM"             | 等價於 "EPOLLOUT"                               |
   +---------------------------+-------------------------------------------------+
   | "EPOLLWRBAND"             | 可以写入优先级数据。                            |
   +---------------------------+-------------------------------------------------+
   | "EPOLLMSG"                | 忽略                                            |
   +---------------------------+-------------------------------------------------+

   3.6 版新加入: 增加了 "EPOLLEXCLUSIVE"。仅支持 Linux Kernel 4.5 或更
   高版本。

epoll.close()

   关闭用于控制 epoll 对象的文件描述符。

epoll.closed

   如果 epoll 对象已关闭，则返回 "True"。

epoll.fileno()

   返回文件描述符对应的数字，该描述符用于控制 epoll 对象。

epoll.fromfd(fd)

   根据给定的文件描述符创建 epoll 对象。

epoll.register(fd[, eventmask])

   在 epoll 对象中注册一个文件描述符。

epoll.modify(fd, eventmask)

   修改一个已注册的文件描述符。

epoll.unregister(fd)

   从 epoll 对象中删除一个已注册的文件描述符。

   3.9 版更變: 此方法不会再忽略 "EBADF" 错误。

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

   等待事件发生，timeout 是浮点数，单位为秒。

   3.5 版更變: 现在，当本函数被信号中断时，重试超时将从头开始计时，不
   会抛出 "InterruptedError" 异常。除非信号处理程序抛出异常（相关原理
   请参阅 **PEP 475**）。


Poll 对象
=========

大多数 Unix 系统支持 "poll()" 系统调用，为服务器提供了更好的可伸缩性，
使服务器可以同时服务于大量客户端。"poll()" 的伸缩性更好，因为该调用内
部仅列出所关注的文件描述符，而 "select()" 会构造一个 bitmap，在其中将
所关注的描述符所对应的 bit 打开，然后重新遍历整个 bitmap。因此
"select()" 复杂度是 O（最高文件描述符），而 "poll()" 是 O（文件描述符
数量）。

poll.register(fd[, eventmask])

   在轮询对象中注册文件描述符。这样，将来调用 "poll()" 方法时将检查文
   件描述符是否有未处理的 I/O 事件。*fd* 可以是整数，也可以是带有
   "fileno()" 方法的对象（该方法返回一个整数）。文件对象已经实现了
   "fileno()"，因此它们也可以用作参数。

   *eventmask* 是可选的位掩码，用于指定要检查的事件类型，它可以是常量
   "POLLIN"、"POLLPRI" 和 "POLLOUT" 的组合，如下表所述。如果未指定本参
   数，默认将会检查所有 3 种类型的事件。

   +---------------------+--------------------------------------------+
   | 常數                | 含意                                       |
   |=====================|============================================|
   | "POLLIN"            | 有要读取的数据                             |
   +---------------------+--------------------------------------------+
   | "POLLPRI"           | 有紧急数据需要读取                         |
   +---------------------+--------------------------------------------+
   | "POLLOUT"           | 准备输出：写不会阻塞                       |
   +---------------------+--------------------------------------------+
   | "POLLERR"           | 某种错误条件                               |
   +---------------------+--------------------------------------------+
   | "POLLHUP"           | 挂起                                       |
   +---------------------+--------------------------------------------+
   | "POLLRDHUP"         | 流套接字的对侧关闭了连接，或关闭了写入到一 |
   |                     | 半的连接                                   |
   +---------------------+--------------------------------------------+
   | "POLLNVAL"          | 无效的请求：描述符未打开                   |
   +---------------------+--------------------------------------------+

   注册已注册过的文件描述符不会报错，且等同于只注册一次该描述符。

poll.modify(fd, eventmask)

   修改一个已注册的文件描述符，等同于 "register(fd, eventmask)"。尝试
   修改未注册的文件描述符会抛出 "OSError" 异常，错误码为 "ENOENT"。

poll.unregister(fd)

   删除轮询对象正在跟踪的某个文件描述符。与 "register()" 方法类似，
   *fd* 可以是整数，也可以是带有 "fileno()" 方法的对象（该方法返回一个
   整数）。

   尝试删除从未注册过的文件描述符会抛出 "KeyError" 异常。

poll.poll([timeout])

   轮询已注册的文件描述符的集合，并返回一个列表，列表可能为空，也可能
   有多个 "(fd, event)" 2元组，其中包含了要报告事件或错误的描述符。
   *fd* 是文件描述符，*event* 是一个位掩码，表示该描述符所报告的事件
   --- "POLLIN" 表示等待输入，"POLLOUT" 表示该描述符可以写入，依此类推
   。 空列表表示调用超时，没有任何文件描述符报告事件。 如果指定了
   *timeout*，它将指定系统等待事件时，等待多长时间后返回（以毫秒为单位
   ）。如果 *timeout* 被省略、为 -1 或为 "None"，则本调用将阻塞，直到
   轮询对象发生事件为止。

   3.5 版更變: 现在，当本函数被信号中断时，重试超时将从头开始计时，不
   会抛出 "InterruptedError" 异常。除非信号处理程序抛出异常（相关原理
   请参阅 **PEP 475**）。


Kqueue 对象
===========

kqueue.close()

   关闭用于控制 kqueue 对象的文件描述符。

kqueue.closed

   如果 kqueue 对象已关闭，则返回 "True"。

kqueue.fileno()

   返回文件描述符对应的数字，该描述符用于控制 epoll 对象。

kqueue.fromfd(fd)

   根据给定的文件描述符创建 kqueue 对象。

kqueue.control(changelist, max_events[, timeout]) -> eventlist

   Kevent 的低级接口

   * changelist 必须是一个可迭代对象，迭代出 kevent 对象，否则置为
     "None"。

   * max_events 必须是 0 或一个正整数。

   * timeout 单位为秒（一般为浮点数），默认为 "None"，即永不超时。

   3.5 版更變: 现在，当本函数被信号中断时，重试超时将从头开始计时，不
   会抛出 "InterruptedError" 异常。除非信号处理程序抛出异常（相关原理
   请参阅 **PEP 475**）。


Kevent 对象
===========

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

kevent.ident

   用于区分事件的标识值。其解释取决于筛选器，但该值通常是文件描述符。
   在构造函数中，该标识值可以是整数或带有 "fileno()" 方法的对象。
   kevent 在内部存储整数。

kevent.filter

   内核筛选器的名称。

   +-----------------------------+-----------------------------------------------+
   | 常數                        | 含意                                          |
   |=============================|===============================================|
   | "KQ_FILTER_READ"            | 获取描述符，并在有数据可读时返回              |
   +-----------------------------+-----------------------------------------------+
   | "KQ_FILTER_WRITE"           | 获取描述符，并在有数据可写时返回              |
   +-----------------------------+-----------------------------------------------+
   | "KQ_FILTER_AIO"             | AIO 请求                                      |
   +-----------------------------+-----------------------------------------------+
   | "KQ_FILTER_VNODE"           | 当在 *fflag* 中监视的一个或多个请求事件发生时 |
   |                             | 返回                                          |
   +-----------------------------+-----------------------------------------------+
   | "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"              | Permitscontrol() 返回事件                     |
   +-----------------------------+-----------------------------------------------+
   | "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" filter flags:

   +------------------------------+----------------------------------------------+
   | 常數                         | 含意                                         |
   |==============================|==============================================|
   | "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

   用户自定义值。
