select —- 等待 I/O 完成

This module provides access to the select() and poll() functionsavailable in most operating systems, devpoll() available onSolaris and derivatives, epoll() available on Linux 2.5+ andkqueue() available on most BSD.Note that on Windows, it only works for sockets; on other operating systems,it also works for other file types (in particular, on Unix, it works on pipes).It cannot be used on regular files to determine whether a file has grown sinceit was last read.

注解

The selectors module allows high-level and efficient I/Omultiplexing, built upon the select module primitives. Users areencouraged to use the selectors module instead, unless they wantprecise control over the OS-level primitives used.

该模块定义以下内容：

  • exception select.error
  • 一个被弃用的 OSError 的别名。

在 3.3 版更改: 根据 PEP 3151，这个类是 OSError 的别名。

  • select.devpoll()
  • (Only supported on Solaris and derivatives.) Returns a /dev/pollpolling object; see section /dev/poll Polling Objects below for themethods supported by devpoll objects.

devpoll() objects are linked to the number of filedescriptors allowed at the time of instantiation. If your programreduces this value, devpoll() will fail. If your programincreases this value, devpoll() may return anincomplete list of active file descriptors.

新的文件描述符 non-inheritable.

3.3 新版功能.

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

  • select.epoll(sizehint=-1, flags=0)
  • (Only supported on Linux 2.5.44 and newer.) Return an edge polling object,which can be used as Edge or Level Triggered interface for I/Oevents.

sizehint informs epoll about the expected number of events to beregistered. It must be positive, or -1 to use the default. It is onlyused on older systems where epoll_create1() is not available;otherwise it has no effect (though its value is still checked).

flags is deprecated and completely ignored. However, when supplied, itsvalue must be 0 or select.EPOLL_CLOEXEC, otherwise OSError israised.

See the Edge and Level Trigger Polling (epoll) Objects section below for the methods supported byepolling objects.

epoll objects support the context management protocol: when used in awith statement, the new file descriptor is automatically closedat the end of the block.

新的文件描述符 non-inheritable.

在 3.3 版更改: 增加了 flags 参数。

在 3.4 版更改: Support for the with statement was added.The new file descriptor is now non-inheritable.

3.4 版后已移除: The flags parameter. select.EPOLL_CLOEXEC is used by default now.Use os.set_inheritable() to make the file descriptor inheritable.

  • select.poll()

  • (Not supported by all operating systems.) Returns a polling object, whichsupports registering and unregistering file descriptors, and then polling themfor I/O events; see section Polling Objects below for the methods supportedby polling objects.

  • select.kqueue()

  • (Only supported on BSD.) Returns a kernel queue object; see sectionKqueue 对象 below for the methods supported by kqueue objects.

新的文件描述符 non-inheritable.

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

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

  • (Only supported on BSD.) Returns a kernel event object; see sectionKevent 对象 below for the methods supported by kevent objects.

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

  • This is a straightforward interface to the Unix select() system call.The first three arguments are sequences of 'waitable objects': eitherintegers representing file descriptors or objects with a parameterless methodnamed fileno() returning such an integer:

    • rlist: wait until ready for reading

    • wlist: wait until ready for writing

    • xlist: wait for an "exceptional condition" (see the manual page for whatyour system considers such a condition)

Empty sequences are allowed, but acceptance of three empty sequences isplatform-dependent. (It is known to work on Unix but not on Windows.) Theoptional timeout argument specifies a time-out as a floating point numberin seconds. When the timeout argument is omitted the function blocks untilat least one file descriptor is ready. A time-out value of zero specifies apoll and never blocks.

The return value is a triple of lists of objects that are ready: subsets of thefirst three arguments. When the time-out is reached without a file descriptorbecoming ready, three empty lists are returned.

Among the acceptable object types in the sequences are Python fileobjects (e.g. sys.stdin, or objects returned byopen() or os.popen()), socket objects returned bysocket.socket(). You may also define a wrapper class yourself,as long as it has an appropriate fileno() method (thatreally returns a file descriptor, not just a random integer).

注解

File objects on Windows are not acceptable, but sockets are. On Windows,the underlying select() function is provided by the WinSocklibrary, and does not handle file descriptors that don't originate fromWinSock.

在 3.5 版更改: The function is now retried with a recomputed timeout when interrupted bya signal, except if the signal handler raises an exception (seePEP 475 for the rationale), instead of raisingInterruptedError.

  • select.PIPE_BUF
  • The minimum number of bytes which can be written without blocking to a pipewhen the pipe has been reported as ready for writing by select(),poll() or another interface in this module. This doesn't applyto other kind of file-like objects such as sockets.

This value is guaranteed by POSIX to be at least 512.

Availability: Unix

3.2 新版功能.

/dev/poll Polling Objects

Solaris and derivatives have /dev/poll. While select() isO(highest file descriptor) and poll() is O(number of filedescriptors), /dev/poll is O(active file descriptors).

/dev/poll behaviour is very close to the standard poll()object.

  • devpoll.close()
  • Close the file descriptor of the polling object.

3.4 新版功能.

  • devpoll.closed
  • True if the polling object is closed.

3.4 新版功能.

  • devpoll.fileno()
  • Return the file descriptor number of the polling object.

3.4 新版功能.

  • devpoll.register(fd[, eventmask])
  • Register a file descriptor with the polling object. Future calls to thepoll() method will then check whether the file descriptor has anypending I/O events. fd can be either an integer, or an object with afileno() method that returns an integer. File objectsimplement fileno(), so they can also be used as the argument.

eventmask is an optional bitmask describing the type of events you want tocheck for. The constants are the same that with poll()object. The default value is a combination of the constants POLLIN,POLLPRI, and POLLOUT.

警告

Registering a file descriptor that's already registered is not anerror, but the result is undefined. The appropriate action is tounregister or modify it first. This is an important differencecompared with poll().

  • devpoll.modify(fd[, eventmask])

  • This method does an unregister() followed by aregister(). It is (a bit) more efficient that doing the sameexplicitly.

  • devpoll.unregister(fd)

  • Remove a file descriptor being tracked by a polling object. Just like theregister() method, fd can be an integer or an object with afileno() method that returns an integer.

Attempting to remove a file descriptor that was never registered issafely ignored.

  • devpoll.poll([timeout])
  • Polls the set of registered file descriptors, and returns a possibly-empty listcontaining (fd, event) 2-tuples for the descriptors that have events orerrors to report. fd is the file descriptor, and event is a bitmask withbits set for the reported events for that descriptor —- POLLIN forwaiting input, POLLOUT to indicate that the descriptor can be writtento, and so forth. An empty list indicates that the call timed out and no filedescriptors had any events to report. If timeout is given, it specifies thelength of time in milliseconds which the system will wait for events beforereturning. If timeout is omitted, -1, or None, the call willblock until there is an event for this poll object.

在 3.5 版更改: The function is now retried with a recomputed timeout when interrupted bya signal, except if the signal handler raises an exception (seePEP 475 for the rationale), instead of raisingInterruptedError.

Edge and Level Trigger Polling (epoll) Objects

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

屏蔽事件

常数

意义

EPOLLIN

可读

EPOLLOUT

可写

EPOLLPRI

紧急数据读取

EPOLLERR

Error condition happened on the assoc. fd

EPOLLHUP

Hang up happened on the assoc. fd

EPOLLET

Set Edge Trigger behavior, the default isLevel Trigger behavior

EPOLLONESHOT

Set one-shot behavior. After one event ispulled out, the fd is internally disabled

EPOLLEXCLUSIVE

Wake only one epoll object when theassociated fd has an event. The default (ifthis flag is not set) is to wake all epollobjects polling on a fd.

EPOLLRDHUP

Stream socket peer closed connection or shutdown writing half of connection.

EPOLLRDNORM

Equivalent to EPOLLIN

EPOLLRDBAND

可以读取优先数据带。

EPOLLWRNORM

Equivalent to EPOLLOUT

EPOLLWRBAND

可以写入优先级数据。

EPOLLMSG

忽略

3.6 新版功能: EPOLLEXCLUSIVE was added. It's only supported by Linux Kernel 4.5or later.

  • epoll.close()

  • Close the control file descriptor of the epoll object.

  • epoll.closed

  • True if the epoll object is closed.

  • epoll.fileno()

  • Return the file descriptor number of the control fd.

  • epoll.fromfd(fd)

  • Create an epoll object from a given file descriptor.

  • epoll.register(fd[, eventmask])

  • Register a fd descriptor with the epoll object.

  • epoll.modify(fd, eventmask)

  • Modify a registered file descriptor.

  • epoll.unregister(fd)

  • Remove a registered file descriptor from the epoll object.

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

  • Wait for events. timeout in seconds (float)

在 3.5 版更改: The function is now retried with a recomputed timeout when interrupted bya signal, except if the signal handler raises an exception (seePEP 475 for the rationale), instead of raisingInterruptedError.

Polling Objects

The poll() system call, supported on most Unix systems, provides betterscalability for network servers that service many, many clients at the sametime. poll() scales better because the system call only requires listingthe file descriptors of interest, while select() builds a bitmap, turnson bits for the fds of interest, and then afterward the whole bitmap has to belinearly scanned again. select() is O(highest file descriptor), whilepoll() is O(number of file descriptors).

  • poll.register(fd[, eventmask])
  • Register a file descriptor with the polling object. Future calls to thepoll() method will then check whether the file descriptor has anypending I/O events. fd can be either an integer, or an object with afileno() method that returns an integer. File objectsimplement fileno(), so they can also be used as the argument.

eventmask is an optional bitmask describing the type of events you want tocheck for, and can be a combination of the constants POLLIN,POLLPRI, and POLLOUT, described in the table below. If notspecified, the default value used will check for all 3 types of events.

常数

意义

POLLIN

有要读取的数据

POLLPRI

有紧急数据需要读取

POLLOUT

准备输出：写不会阻塞

POLLERR

某种错误条件

POLLHUP

挂起

POLLRDHUP

流套接字对等体关闭连接，或关闭写入一半连接

POLLNVAL

无效的请求：描述符未打开

Registering a file descriptor that's already registered is not an error, and hasthe same effect as registering the descriptor exactly once.

  • poll.modify(fd, eventmask)

  • Modifies an already registered fd. This has the same effect asregister(fd, eventmask). Attempting to modify a file descriptorthat was never registered causes an OSError exception with errnoENOENT to be raised.

  • poll.unregister(fd)

  • Remove a file descriptor being tracked by a polling object. Just like theregister() method, fd can be an integer or an object with afileno() method that returns an integer.

Attempting to remove a file descriptor that was never registered causes aKeyError exception to be raised.

  • poll.poll([timeout])
  • Polls the set of registered file descriptors, and returns a possibly-empty listcontaining (fd, event) 2-tuples for the descriptors that have events orerrors to report. fd is the file descriptor, and event is a bitmask withbits set for the reported events for that descriptor —- POLLIN forwaiting input, POLLOUT to indicate that the descriptor can be writtento, and so forth. An empty list indicates that the call timed out and no filedescriptors had any events to report. If timeout is given, it specifies thelength of time in milliseconds which the system will wait for events beforereturning. If timeout is omitted, negative, or None, the call willblock until there is an event for this poll object.

在 3.5 版更改: The function is now retried with a recomputed timeout when interrupted bya signal, except if the signal handler raises an exception (seePEP 475 for the rationale), instead of raisingInterruptedError.

Kqueue 对象

  • kqueue.close()

  • Close the control file descriptor of the kqueue object.

  • kqueue.closed

  • True if the kqueue object is closed.

  • kqueue.fileno()

  • Return the file descriptor number of the control fd.

  • kqueue.fromfd(fd)

  • Create a kqueue object from a given file descriptor.

  • kqueue.control(changelist, max_events[, timeout]) → eventlist

  • Low level interface to kevent

    • changelist must be an iterable of kevent objects or None

    • max_events must be 0 or a positive integer

    • timeout in seconds (floats possible); the default is None,to wait forever

在 3.5 版更改: The function is now retried with a recomputed timeout when interrupted bya signal, except if the signal handler raises an exception (seePEP 475 for the rationale), instead of raisingInterruptedError.

Kevent 对象

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

  • kevent.ident

  • Value used to identify the event. The interpretation depends on the filterbut it's usually the file descriptor. In the constructor ident can eitherbe an int or an object with a fileno() method. keventstores the integer internally.

  • kevent.filter

  • 内核过滤器的名称。

常数

意义

KQ_FILTER_READ

获取描述符，并在有数据可读时返回

KQ_FILTER_WRITE

获取描述符，并在有数据可写时返回

KQ_FILTER_AIO

AIO 请求

KQ_FILTER_VNODE

当在 fflag 中监视的一个或多个请求事件发生时返回

KQ_FILTER_PROC

监视进程ID上的事件

KQ_FILTER_NETDEV

观察网络设备上的事件[在Mac OS X上不可用]

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 过滤器标志（在Mac OS X上不可用）：

常数

意义

KQ_NOTE_LINKUP

链接已建立

KQ_NOTE_LINKDOWN

链接已断开

KQ_NOTE_LINKINV

链接状态无效

  • kevent.data

  • 过滤特定数据。

  • kevent.udata

  • 用户定义的值。