select
— 等待 I/O 完成¶
该模块提供了对 select()
和 poll()
函数的访问,这些函数在大多数操作系统中是可用的。在 Solaris 及其衍生版本上可用 devpoll()
,在 Linux 2.5+ 上可用 epoll()
,在大多数 BSD 上可用 kqueue()
。注意,在 Windows 上,本模块仅适用于套接字;在其他操作系统上,本模块也适用于其他文件类型(特别地,在 Unix 上也适用于管道)。本模块不能用于常规文件,不能检测出(自上次读取文件后)文件是否有新数据写入。
Availability: not Emscripten, not WASI.
This module does not work or is not available on WebAssembly platforms
wasm32-emscripten
and wasm32-wasi
. See
WebAssembly platforms for more information.
该模块定义以下内容:
- 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 whereepoll_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])¶
Polls the set of registered file descriptors, and returns a possibly empty list containing
(fd, event)
2-tuples for the descriptors that have events or errors to report. fd is the file descriptor, and event is a bitmask with bits set for the reported events for that descriptor —POLLIN
for waiting input,POLLOUT
to indicate that the descriptor can be written to, and so forth. An empty list indicates that the call timed out and no file descriptors had any events to report. If timeout is given, it specifies the length of time in milliseconds which the system will wait for events before returning. If timeout is omitted, -1, orNone
, the call will block until there is an event for this poll object.在 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.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])¶
Polls the set of registered file descriptors, and returns a possibly empty list containing
(fd, event)
2-tuples for the descriptors that have events or errors to report. fd is the file descriptor, and event is a bitmask with bits set for the reported events for that descriptor —POLLIN
for waiting input,POLLOUT
to indicate that the descriptor can be written to, and so forth. An empty list indicates that the call timed out and no file descriptors had any events to report. If timeout is given, it specifies the length of time in milliseconds which the system will wait for events before returning. If timeout is omitted, negative, orNone
, the call will block until there is an event for this poll object.在 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.filter¶
内核筛选器的名称。
常量
含意
KQ_FILTER_READ
获取描述符,并在有数据可读时返回
KQ_FILTER_WRITE
获取描述符,并在有数据可写时返回
KQ_FILTER_AIO
AIO 请求
KQ_FILTER_VNODE
当在 fflag 中监视的一个或多个请求事件发生时返回
KQ_FILTER_PROC
监视进程ID上的事件
KQ_FILTER_NETDEV
Watch for events on a network device [not available on 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
filter flags (not available on macOS):常量
含意
KQ_NOTE_LINKUP
链接已建立
KQ_NOTE_LINKDOWN
链接已断开
KQ_NOTE_LINKINV
链接状态无效
- kevent.data¶
筛选特定数据。
- kevent.udata¶
用户自定义值。