mirror of https://github.com/python/cpython
275 lines
8.6 KiB
ReStructuredText
275 lines
8.6 KiB
ReStructuredText
:mod:`selectors` -- High-level I/O multiplexing
|
|
===============================================
|
|
|
|
.. module:: selectors
|
|
:synopsis: High-level I/O multiplexing.
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
|
|
Introduction
|
|
------------
|
|
|
|
This module allows high-level and efficient I/O multiplexing, built upon the
|
|
:mod:`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 :class:`BaseSelector` abstract base class, along with several
|
|
concrete implementations (:class:`KqueueSelector`, :class:`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
|
|
:meth:`fileno()` method, or a raw file descriptor. See :term:`file object`.
|
|
|
|
:class:`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).
|
|
|
|
.. seealso::
|
|
|
|
:mod:`select`
|
|
Low-level I/O multiplexing module.
|
|
|
|
|
|
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 |
|
|
+=======================+===============================================+
|
|
| :const:`EVENT_READ` | Available for read |
|
|
+-----------------------+-----------------------------------------------+
|
|
| :const:`EVENT_WRITE` | Available for write |
|
|
+-----------------------+-----------------------------------------------+
|
|
|
|
|
|
.. class:: SelectorKey
|
|
|
|
A :class:`SelectorKey` is a :class:`~collections.namedtuple` used to
|
|
associate a file object to its underlying file decriptor, selected event
|
|
mask and attached data. It is returned by several :class:`BaseSelector`
|
|
methods.
|
|
|
|
.. attribute:: fileobj
|
|
|
|
File object registered.
|
|
|
|
.. attribute:: fd
|
|
|
|
Underlying file descriptor.
|
|
|
|
.. attribute:: events
|
|
|
|
Events that must be waited for on this file object.
|
|
|
|
.. attribute:: data
|
|
|
|
Optional opaque data associated to this file object: for example, this
|
|
could be used to store a per-client session ID.
|
|
|
|
|
|
.. class:: BaseSelector
|
|
|
|
A :class:`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
|
|
:class:`DefaultSelector` instead, or one of :class:`SelectSelector`,
|
|
:class:`KqueueSelector` etc. if you want to specifically use an
|
|
implementation, and your platform supports it.
|
|
:class:`BaseSelector` and its concrete implementations support the
|
|
:term:`context manager` protocol.
|
|
|
|
.. method:: register(fileobj, events, data=None)
|
|
|
|
Register a file object for selection, monitoring it for I/O events.
|
|
|
|
*fileobj* is the file object to monitor. It may either be an integer
|
|
file descriptor or an object with a ``fileno()`` method.
|
|
*events* is a bitwise mask of events to monitor.
|
|
*data* is an opaque object.
|
|
|
|
This returns a new :class:`SelectorKey` instance, or raises a
|
|
:exc:`ValueError` in case of invalid event mask or file descriptor, or
|
|
:exc:`KeyError` if the file object is already registered.
|
|
|
|
.. method:: unregister(fileobj)
|
|
|
|
Unregister a file object from selection, removing it from monitoring. A
|
|
file object shall be unregistered prior to being closed.
|
|
|
|
*fileobj* must be a file object previously registered.
|
|
|
|
This returns the associated :class:`SelectorKey` instance, or raises a
|
|
:exc:`KeyError` if *fileobj* is not registered. It will raise
|
|
:exc:`ValueError` if *fileobj* is invalid (e.g. it has no ``fileno()``
|
|
method or its ``fileno()`` method has an invalid return value).
|
|
|
|
.. method:: modify(fileobj, events, data=None)
|
|
|
|
Change a registered file object's monitored events or attached data.
|
|
|
|
This is equivalent to :meth:`BaseSelector.unregister(fileobj)` followed
|
|
by :meth:`BaseSelector.register(fileobj, events, data)`, except that it
|
|
can be implemented more efficiently.
|
|
|
|
This returns a new :class:`SelectorKey` instance, or raises a
|
|
:exc:`ValueError` in case of invalid event mask or file descriptor, or
|
|
:exc:`KeyError` if the file object is not registered.
|
|
|
|
.. method:: select(timeout=None)
|
|
|
|
Wait until some registered file objects become ready, or the timeout
|
|
expires.
|
|
|
|
If ``timeout > 0``, this specifies the maximum wait time, in seconds.
|
|
If ``timeout <= 0``, the call won't block, and will report the currently
|
|
ready file objects.
|
|
If *timeout* is ``None``, the call will block until a monitored file object
|
|
becomes ready.
|
|
|
|
This returns a list of ``(key, events)`` tuples, one for each ready file
|
|
object.
|
|
|
|
*key* is the :class:`SelectorKey` instance corresponding to a ready file
|
|
object.
|
|
*events* is a bitmask of events ready on this file object.
|
|
|
|
.. note::
|
|
This method can return before any file object becomes ready or the
|
|
timeout has elapsed if the current process receives a signal: in this
|
|
case, an empty list will be returned.
|
|
|
|
.. versionchanged:: 3.5
|
|
The selector is now retried with a recomputed timeout when interrupted
|
|
by a signal if the signal handler did not raise an exception (see
|
|
:pep:`475` for the rationale), instead of returning an empty list
|
|
of events before the timeout.
|
|
|
|
.. method:: 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.
|
|
|
|
.. method:: get_key(fileobj)
|
|
|
|
Return the key associated with a registered file object.
|
|
|
|
This returns the :class:`SelectorKey` instance associated to this file
|
|
object, or raises :exc:`KeyError` if the file object is not registered.
|
|
|
|
.. method:: get_map()
|
|
|
|
Return a mapping of file objects to selector keys.
|
|
|
|
This returns a :class:`~collections.abc.Mapping` instance mapping
|
|
registered file objects to their associated :class:`SelectorKey`
|
|
instance.
|
|
|
|
|
|
.. class:: 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:: SelectSelector()
|
|
|
|
:func:`select.select`-based selector.
|
|
|
|
|
|
.. class:: PollSelector()
|
|
|
|
:func:`select.poll`-based selector.
|
|
|
|
|
|
.. class:: EpollSelector()
|
|
|
|
:func:`select.epoll`-based selector.
|
|
|
|
.. method:: fileno()
|
|
|
|
This returns the file descriptor used by the underlying
|
|
:func:`select.epoll` object.
|
|
|
|
.. class:: DevpollSelector()
|
|
|
|
:func:`select.devpoll`-based selector.
|
|
|
|
.. method:: fileno()
|
|
|
|
This returns the file descriptor used by the underlying
|
|
:func:`select.devpoll` object.
|
|
|
|
.. versionadded:: 3.5
|
|
|
|
.. class:: KqueueSelector()
|
|
|
|
:func:`select.kqueue`-based selector.
|
|
|
|
.. method:: fileno()
|
|
|
|
This returns the file descriptor used by the underlying
|
|
:func:`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)
|