select --- 等待 I/O 完成

---

该模块提供了对 select() 和 poll() 函数的访问，这在大多数操作系统上都是可用的，devpoll() 在 Solaris 及其衍生系统上可用，epoll() 在 Linux 2.5+ 上可用，而 kqueue() 在大多数 BSD 上可用。注意在 Windows 上，它仅适用于套接字；在其他操作系统上，它还适用于其他文件类型（特别是在 Unix 上，它还适用于管道）。 它不能被用在常规文件上确定一个文件自其最后一次被读取后大小是否有增长。

备注

selectors 模块允许高层级且高效的 I/O 利用，它构建于 select 模块原语的基础之上。 推荐用户改用 selectors 模块，除非用户希望对所用的 OS 层级原语进行精确控制。

适用范围: not WASI.

此模块在 WebAssembly 平台上无效或不可用。请参阅 WebAssembly 平台 了解详情。

该模块定义以下内容：

exception select.error

一个被弃用的 OSError 的别名。

在 3.3 版本发生变更: 根据 PEP 3151，这个类是 OSError 的别名。

select.devpoll()

返回一个 /dev/poll 轮询对象；请参阅下面的 /dev/poll polling objects 一节了解 devpoll 对象所支持的方法。

devpoll() 对象与实例化时允许的文件描述符数量相关联。如果你的程序减少该值，devpoll() 将会失败。 如果你的程序增加该值，devpoll() 可能会返回不完整的活动文件描述符列表。

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

Added in version 3.3.

在 3.4 版本发生变更: 新的文件描述符现在是不可继承的。

适用范围: Solaris.

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

返回一个 edge 轮询对象，它可被用作 I/O 事件的 Edge 或 Level 触发接口。

sizehint 告诉 epoll 预计要注册的事件数量。 该值必须为正数，或为 -1 表示使用默认值。 它仅在 epoll_create1(2) 不可用的旧系统上会被使用；在其他情况下它不会产生影响（尽管该值仍会被检查）。

flags 已经弃用且完全被忽略。但是，如果提供该值，则它必须是 0 或 select.EPOLL_CLOEXEC，否则会抛出 OSError 异常。

请参阅下方 Edge and level trigger polling (epoll) objects 获取 epoll 对象所支持的方法。

epoll 对象支持上下文管理器：当在 with 语句中使用时，新建的文件描述符会在运行至语句块结束时自动关闭。

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

在 3.3 版本发生变更: 增加了 flags 参数。

在 3.4 版本发生变更: 增加了对 with 语句的支持。新的文件描述符现在是不可继承的。

自 3.4 版本弃用: flags 参数。现在默认采用 select.EPOLL_CLOEXEC 标志。使用 os.set_inheritable() 来让文件描述符可继承。

在 3.15 版本发生变更: 在构建 CPython 时，可使用 --disable-epoll 来禁用此函数。

适用范围: Linux >= 2.5.44.

select.poll()

返回一个轮询对象，它支持注册和注销文件描述符，然后轮询它们以获取 I/O 事件；请参阅下面的 Polling objects 一节了解轮询对象支持的方法。

适用范围: Unix.

select.kqueue()

返回一个内核队列对象；请参阅下面的 Kqueue objects 一节了解 kqueue 对象支持的方法。

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

在 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：等待“异常情况”（请参阅当前系统的手册，以获取哪些情况称为异常情况）

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 in seconds; it may be a non-integer to specify fractions of 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.

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

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

备注

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

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

在 3.15 版本发生变更: 接受任意实数作为 timeout，而不是只接受整数或浮点数。

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

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

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

在 3.15 版本发生变更: 接受任意实数作为 timeout，而不是只接受整数或浮点数。

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	忽略
EPOLLWAKEUP	防止在事件等待期间休眠。

Added in version 3.6: 增加了 EPOLLEXCLUSIVE。仅支持 Linux Kernel 4.5 或更高版本。

Added in version 3.14: 增加了 EPOLLWAKEUP。仅受 Linux 3.5 或更新的内核支持。

epoll.close()

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

epoll.closed

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

epoll.fileno()

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

epoll.fromfd(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 对象中删除一个已注册的文件描述符。

在 3.9 版本发生变更: 此方法不会再忽略 EBADF 错误。

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

Wait for events. If timeout is given, it specifies the length of time in seconds (may be non-integer) which the system will wait for events before returning.

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

在 3.15 版本发生变更: 接受任意实数作为 timeout，而不是只接受整数或浮点数。

Polling objects

大多数 Unix 系统都支持 poll() 系统调用，它为网络服务器提供了更好的可伸缩性，可以同时为大量客户端提供服务。 poll() 的可伸缩性更好是因为该系统只须列出要关注的文件描述符，而 select() 则会构建一个位映射表，打开这个要关注的描述符所对应的比特位，然后再次线性扫描整个位映射表。 select() 的复杂度为 O(最高文件描述符)，而 poll() 则为 O(文件描述符的数量)。

poll.register(fd[, eventmask])

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

eventmask 是可选的位掩码，用于指定要检查的事件类型，它可以是常量 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)

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

poll.unregister(fd)

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

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

poll.poll([timeout])

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

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

在 3.15 版本发生变更: Accepts any real number as timeout, not only integer or float. If ppoll() function is available, timeout has a resolution of 1 ns (1e-6 ms) instead of 1 ms.

Kqueue objects

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 in seconds (non-integers are possible); the default is None, to wait forever

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

在 3.15 版本发生变更: 接受任意实数作为 timeout，而不是只接受整数或浮点数。

Kevent objects

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

kevent.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.