selectors — High-level I/O multiplexing — Python documentation
selectors — High-level I/O multiplexing
New in version 3.4.
Source code: :source:`Lib/selectors.py`
Introduction
This module allows high-level and efficient I/O multiplexing, built upon the select module primitives. Users are encouraged to use this module instead, unless they want precise control over the OS-level primitives used.
It defines a BaseSelector abstract base class, along with several concrete implementations (KqueueSelector, EpollSelector…), that can be used to wait for I/O readiness notification on multiple file objects. In the following, “file object” refers to any object with a fileno()
method, or a raw file descriptor. See file object.
DefaultSelector is an alias to the most efficient implementation available on the current platform: this should be the default choice for most users.
Note
The type of file objects supported depends on the platform: on Windows, sockets are supported, but not pipes, whereas on Unix, both are supported (some other types may be supported as well, such as fifos or special file devices).
Classes
Classes hierarchy:
BaseSelector
+-- SelectSelector
+-- PollSelector
+-- EpollSelector
+-- DevpollSelector
+-- KqueueSelector
In the following, events is a bitwise mask indicating which I/O events should be waited for on a given file object. It can be a combination of the modules constants below:
Constant Meaning EVENT_READ
Available for read EVENT_WRITE
Available for write
- class selectors.SelectorKey
A SelectorKey is a namedtuple used to associate a file object to its underlying file descriptor, selected event mask and attached data. It is returned by several BaseSelector methods.
- fileobj
File object registered.
- fd
Underlying file descriptor.
- events
Events that must be waited for on this file object.
- data
Optional opaque data associated to this file object: for example, this could be used to store a per-client session ID.
- class selectors.BaseSelector
A BaseSelector is used to wait for I/O event readiness on multiple file objects. It supports file stream registration, unregistration, and a method to wait for I/O events on those streams, with an optional timeout. It’s an abstract base class, so cannot be instantiated. Use DefaultSelector instead, or one of SelectSelector, KqueueSelector etc. if you want to specifically use an implementation, and your platform supports it. BaseSelector and its concrete implementations support the context manager protocol.
- modify(fileobj, events, data=None)
Change a registered file object’s monitored events or attached data.
This is equivalent to
BaseSelector.unregister(fileobj)()
followed byBaseSelector.register(fileobj, events, data)()
, except that it can be implemented more efficiently.This returns a new SelectorKey instance, or raises a ValueError in case of invalid event mask or file descriptor, or KeyError if the file object is not registered.
- close()
Close the selector.
This must be called to make sure that any underlying resource is freed. The selector shall not be used once it has been closed.
- get_key(fileobj)
Return the key associated with a registered file object.
This returns the SelectorKey instance associated to this file object, or raises KeyError if the file object is not registered.
- class selectors.DefaultSelector
- The default selector class, using the most efficient implementation available on the current platform. This should be the default choice for most users.
- class selectors.SelectSelector
- select.select()-based selector.
- class selectors.PollSelector
- select.poll()-based selector.
- class selectors.EpollSelector
- select.epoll()-based selector.
- fileno()
- This returns the file descriptor used by the underlying select.epoll() object.
- class selectors.DevpollSelector
select.devpoll()-based selector.
- fileno()
This returns the file descriptor used by the underlying select.devpoll() object.
New in version 3.5.
- class selectors.KqueueSelector
- select.kqueue()-based selector.
- fileno()
- This returns the file descriptor used by the underlying select.kqueue() object.
Examples
Here is a simple echo server implementation:
import selectors
import socket
sel = selectors.DefaultSelector()
def accept(sock, mask):
conn, addr = sock.accept() # Should be ready
print('accepted', conn, 'from', addr)
conn.setblocking(False)
sel.register(conn, selectors.EVENT_READ, read)
def read(conn, mask):
data = conn.recv(1000) # Should be ready
if data:
print('echoing', repr(data), 'to', conn)
conn.send(data) # Hope it won't block
else:
print('closing', conn)
sel.unregister(conn)
conn.close()
sock = socket.socket()
sock.bind(('localhost', 1234))
sock.listen(100)
sock.setblocking(False)
sel.register(sock, selectors.EVENT_READ, accept)
while True:
events = sel.select()
for key, mask in events:
callback = key.data
callback(key.fileobj, mask)