| :mod:`selectors` --- High-level I/O multiplexing |
| ================================================ |
| |
| .. module:: selectors |
| :synopsis: High-level I/O multiplexing. |
| |
| .. versionadded:: 3.4 |
| |
| **Source code:** :source:`Lib/selectors.py` |
| |
| -------------- |
| |
| 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. |
| |
| .. abstractmethod:: 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. |
| |
| .. abstractmethod:: 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. |
| |
| .. abstractmethod:: 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. |
| |
| .. abstractmethod:: 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) |