Serhiy Storchaka | 29b0a26 | 2016-12-04 10:20:55 +0200 | [diff] [blame] | 1 | :mod:`selectors` --- High-level I/O multiplexing |
| 2 | ================================================ |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 3 | |
| 4 | .. module:: selectors |
| 5 | :synopsis: High-level I/O multiplexing. |
| 6 | |
| 7 | .. versionadded:: 3.4 |
| 8 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 9 | **Source code:** :source:`Lib/selectors.py` |
| 10 | |
| 11 | -------------- |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 12 | |
| 13 | Introduction |
| 14 | ------------ |
| 15 | |
| 16 | This module allows high-level and efficient I/O multiplexing, built upon the |
| 17 | :mod:`select` module primitives. Users are encouraged to use this module |
| 18 | instead, unless they want precise control over the OS-level primitives used. |
| 19 | |
| 20 | It defines a :class:`BaseSelector` abstract base class, along with several |
| 21 | concrete implementations (:class:`KqueueSelector`, :class:`EpollSelector`...), |
| 22 | that can be used to wait for I/O readiness notification on multiple file |
| 23 | objects. In the following, "file object" refers to any object with a |
| 24 | :meth:`fileno()` method, or a raw file descriptor. See :term:`file object`. |
| 25 | |
| 26 | :class:`DefaultSelector` is an alias to the most efficient implementation |
| 27 | available on the current platform: this should be the default choice for most |
| 28 | users. |
| 29 | |
| 30 | .. note:: |
| 31 | The type of file objects supported depends on the platform: on Windows, |
| 32 | sockets are supported, but not pipes, whereas on Unix, both are supported |
| 33 | (some other types may be supported as well, such as fifos or special file |
| 34 | devices). |
| 35 | |
| 36 | .. seealso:: |
| 37 | |
| 38 | :mod:`select` |
| 39 | Low-level I/O multiplexing module. |
| 40 | |
| 41 | |
| 42 | Classes |
| 43 | ------- |
| 44 | |
| 45 | Classes hierarchy:: |
| 46 | |
| 47 | BaseSelector |
| 48 | +-- SelectSelector |
| 49 | +-- PollSelector |
| 50 | +-- EpollSelector |
Giampaolo Rodola' | f97e829 | 2014-03-20 21:43:41 +0100 | [diff] [blame] | 51 | +-- DevpollSelector |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 52 | +-- KqueueSelector |
| 53 | |
| 54 | |
| 55 | In the following, *events* is a bitwise mask indicating which I/O events should |
Brett Cannon | aa00324 | 2015-09-18 15:21:02 -0700 | [diff] [blame] | 56 | be waited for on a given file object. It can be a combination of the modules |
| 57 | constants below: |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 58 | |
| 59 | +-----------------------+-----------------------------------------------+ |
| 60 | | Constant | Meaning | |
| 61 | +=======================+===============================================+ |
| 62 | | :const:`EVENT_READ` | Available for read | |
| 63 | +-----------------------+-----------------------------------------------+ |
| 64 | | :const:`EVENT_WRITE` | Available for write | |
| 65 | +-----------------------+-----------------------------------------------+ |
| 66 | |
| 67 | |
| 68 | .. class:: SelectorKey |
| 69 | |
| 70 | A :class:`SelectorKey` is a :class:`~collections.namedtuple` used to |
Tong SHEN | b0d8203 | 2017-05-02 21:27:57 +0800 | [diff] [blame] | 71 | associate a file object to its underlying file descriptor, selected event |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 72 | mask and attached data. It is returned by several :class:`BaseSelector` |
| 73 | methods. |
| 74 | |
| 75 | .. attribute:: fileobj |
| 76 | |
| 77 | File object registered. |
| 78 | |
| 79 | .. attribute:: fd |
| 80 | |
| 81 | Underlying file descriptor. |
| 82 | |
| 83 | .. attribute:: events |
| 84 | |
Andrew Kuchling | b3931d2 | 2013-11-22 16:15:28 -0500 | [diff] [blame] | 85 | Events that must be waited for on this file object. |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 86 | |
| 87 | .. attribute:: data |
| 88 | |
| 89 | Optional opaque data associated to this file object: for example, this |
Andrew Kuchling | b3931d2 | 2013-11-22 16:15:28 -0500 | [diff] [blame] | 90 | could be used to store a per-client session ID. |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 91 | |
| 92 | |
| 93 | .. class:: BaseSelector |
| 94 | |
| 95 | A :class:`BaseSelector` is used to wait for I/O event readiness on multiple |
| 96 | file objects. It supports file stream registration, unregistration, and a |
| 97 | method to wait for I/O events on those streams, with an optional timeout. |
| 98 | It's an abstract base class, so cannot be instantiated. Use |
| 99 | :class:`DefaultSelector` instead, or one of :class:`SelectSelector`, |
| 100 | :class:`KqueueSelector` etc. if you want to specifically use an |
| 101 | implementation, and your platform supports it. |
| 102 | :class:`BaseSelector` and its concrete implementations support the |
| 103 | :term:`context manager` protocol. |
| 104 | |
Berker Peksag | 6e9d2e6 | 2015-12-08 12:14:50 +0200 | [diff] [blame] | 105 | .. abstractmethod:: register(fileobj, events, data=None) |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 106 | |
| 107 | Register a file object for selection, monitoring it for I/O events. |
| 108 | |
Guido van Rossum | 9710ff0 | 2013-12-07 15:57:01 -0800 | [diff] [blame] | 109 | *fileobj* is the file object to monitor. It may either be an integer |
| 110 | file descriptor or an object with a ``fileno()`` method. |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 111 | *events* is a bitwise mask of events to monitor. |
| 112 | *data* is an opaque object. |
| 113 | |
| 114 | This returns a new :class:`SelectorKey` instance, or raises a |
| 115 | :exc:`ValueError` in case of invalid event mask or file descriptor, or |
| 116 | :exc:`KeyError` if the file object is already registered. |
| 117 | |
Berker Peksag | 6e9d2e6 | 2015-12-08 12:14:50 +0200 | [diff] [blame] | 118 | .. abstractmethod:: unregister(fileobj) |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 119 | |
| 120 | Unregister a file object from selection, removing it from monitoring. A |
| 121 | file object shall be unregistered prior to being closed. |
| 122 | |
| 123 | *fileobj* must be a file object previously registered. |
| 124 | |
| 125 | This returns the associated :class:`SelectorKey` instance, or raises a |
Guido van Rossum | 9710ff0 | 2013-12-07 15:57:01 -0800 | [diff] [blame] | 126 | :exc:`KeyError` if *fileobj* is not registered. It will raise |
| 127 | :exc:`ValueError` if *fileobj* is invalid (e.g. it has no ``fileno()`` |
| 128 | method or its ``fileno()`` method has an invalid return value). |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 129 | |
| 130 | .. method:: modify(fileobj, events, data=None) |
| 131 | |
Andrew Kuchling | b3931d2 | 2013-11-22 16:15:28 -0500 | [diff] [blame] | 132 | Change a registered file object's monitored events or attached data. |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 133 | |
| 134 | This is equivalent to :meth:`BaseSelector.unregister(fileobj)` followed |
| 135 | by :meth:`BaseSelector.register(fileobj, events, data)`, except that it |
| 136 | can be implemented more efficiently. |
| 137 | |
| 138 | This returns a new :class:`SelectorKey` instance, or raises a |
| 139 | :exc:`ValueError` in case of invalid event mask or file descriptor, or |
| 140 | :exc:`KeyError` if the file object is not registered. |
| 141 | |
Berker Peksag | 6e9d2e6 | 2015-12-08 12:14:50 +0200 | [diff] [blame] | 142 | .. abstractmethod:: select(timeout=None) |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 143 | |
| 144 | Wait until some registered file objects become ready, or the timeout |
| 145 | expires. |
| 146 | |
| 147 | If ``timeout > 0``, this specifies the maximum wait time, in seconds. |
| 148 | If ``timeout <= 0``, the call won't block, and will report the currently |
| 149 | ready file objects. |
| 150 | If *timeout* is ``None``, the call will block until a monitored file object |
| 151 | becomes ready. |
| 152 | |
Andrew Kuchling | b3931d2 | 2013-11-22 16:15:28 -0500 | [diff] [blame] | 153 | This returns a list of ``(key, events)`` tuples, one for each ready file |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 154 | object. |
| 155 | |
| 156 | *key* is the :class:`SelectorKey` instance corresponding to a ready file |
| 157 | object. |
| 158 | *events* is a bitmask of events ready on this file object. |
| 159 | |
Charles-François Natali | 837a6e0 | 2013-12-01 13:23:48 +0100 | [diff] [blame] | 160 | .. note:: |
| 161 | This method can return before any file object becomes ready or the |
| 162 | timeout has elapsed if the current process receives a signal: in this |
| 163 | case, an empty list will be returned. |
| 164 | |
Victor Stinner | b310173 | 2015-03-31 12:08:09 +0200 | [diff] [blame] | 165 | .. versionchanged:: 3.5 |
| 166 | The selector is now retried with a recomputed timeout when interrupted |
| 167 | by a signal if the signal handler did not raise an exception (see |
| 168 | :pep:`475` for the rationale), instead of returning an empty list |
| 169 | of events before the timeout. |
| 170 | |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 171 | .. method:: close() |
| 172 | |
| 173 | Close the selector. |
| 174 | |
| 175 | This must be called to make sure that any underlying resource is freed. |
| 176 | The selector shall not be used once it has been closed. |
| 177 | |
| 178 | .. method:: get_key(fileobj) |
| 179 | |
Andrew Kuchling | b3931d2 | 2013-11-22 16:15:28 -0500 | [diff] [blame] | 180 | Return the key associated with a registered file object. |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 181 | |
| 182 | This returns the :class:`SelectorKey` instance associated to this file |
| 183 | object, or raises :exc:`KeyError` if the file object is not registered. |
| 184 | |
Berker Peksag | 6e9d2e6 | 2015-12-08 12:14:50 +0200 | [diff] [blame] | 185 | .. abstractmethod:: get_map() |
Charles-François Natali | 4574b49 | 2013-10-30 20:31:04 +0100 | [diff] [blame] | 186 | |
| 187 | Return a mapping of file objects to selector keys. |
| 188 | |
| 189 | This returns a :class:`~collections.abc.Mapping` instance mapping |
| 190 | registered file objects to their associated :class:`SelectorKey` |
| 191 | instance. |
| 192 | |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 193 | |
| 194 | .. class:: DefaultSelector() |
| 195 | |
| 196 | The default selector class, using the most efficient implementation |
| 197 | available on the current platform. This should be the default choice for |
| 198 | most users. |
| 199 | |
| 200 | |
| 201 | .. class:: SelectSelector() |
| 202 | |
| 203 | :func:`select.select`-based selector. |
| 204 | |
| 205 | |
| 206 | .. class:: PollSelector() |
| 207 | |
| 208 | :func:`select.poll`-based selector. |
| 209 | |
| 210 | |
| 211 | .. class:: EpollSelector() |
| 212 | |
| 213 | :func:`select.epoll`-based selector. |
| 214 | |
| 215 | .. method:: fileno() |
| 216 | |
| 217 | This returns the file descriptor used by the underlying |
| 218 | :func:`select.epoll` object. |
| 219 | |
Giampaolo Rodola' | f97e829 | 2014-03-20 21:43:41 +0100 | [diff] [blame] | 220 | .. class:: DevpollSelector() |
| 221 | |
| 222 | :func:`select.devpoll`-based selector. |
| 223 | |
| 224 | .. method:: fileno() |
| 225 | |
| 226 | This returns the file descriptor used by the underlying |
| 227 | :func:`select.devpoll` object. |
| 228 | |
Georg Brandl | 77605cb | 2014-03-24 09:06:33 +0100 | [diff] [blame] | 229 | .. versionadded:: 3.5 |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 230 | |
| 231 | .. class:: KqueueSelector() |
| 232 | |
| 233 | :func:`select.kqueue`-based selector. |
| 234 | |
| 235 | .. method:: fileno() |
| 236 | |
| 237 | This returns the file descriptor used by the underlying |
| 238 | :func:`select.kqueue` object. |
| 239 | |
| 240 | |
Guido van Rossum | 8519e5a | 2013-11-29 14:51:18 -0800 | [diff] [blame] | 241 | Examples |
| 242 | -------- |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 243 | |
Guido van Rossum | 8519e5a | 2013-11-29 14:51:18 -0800 | [diff] [blame] | 244 | Here is a simple echo server implementation:: |
| 245 | |
| 246 | import selectors |
| 247 | import socket |
| 248 | |
| 249 | sel = selectors.DefaultSelector() |
| 250 | |
| 251 | def accept(sock, mask): |
| 252 | conn, addr = sock.accept() # Should be ready |
| 253 | print('accepted', conn, 'from', addr) |
| 254 | conn.setblocking(False) |
| 255 | sel.register(conn, selectors.EVENT_READ, read) |
| 256 | |
| 257 | def read(conn, mask): |
| 258 | data = conn.recv(1000) # Should be ready |
| 259 | if data: |
| 260 | print('echoing', repr(data), 'to', conn) |
| 261 | conn.send(data) # Hope it won't block |
| 262 | else: |
| 263 | print('closing', conn) |
| 264 | sel.unregister(conn) |
| 265 | conn.close() |
| 266 | |
| 267 | sock = socket.socket() |
| 268 | sock.bind(('localhost', 1234)) |
| 269 | sock.listen(100) |
| 270 | sock.setblocking(False) |
| 271 | sel.register(sock, selectors.EVENT_READ, accept) |
| 272 | |
| 273 | while True: |
| 274 | events = sel.select() |
| 275 | for key, mask in events: |
| 276 | callback = key.data |
| 277 | callback(key.fileobj, mask) |