1 :mod:`selectors` --- High-level I/O multiplexing 2 ================================================ 3 4 .. module:: selectors 5 :synopsis: High-level I/O multiplexing. 6 7 .. versionadded:: 3.4 8 9 **Source code:** :source:`Lib/selectors.py` 10 11 -------------- 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 51 +-- DevpollSelector 52 +-- KqueueSelector 53 54 55 In the following, *events* is a bitwise mask indicating which I/O events should 56 be waited for on a given file object. It can be a combination of the modules 57 constants below: 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 71 associate a file object to its underlying file decriptor, selected event 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 85 Events that must be waited for on this file object. 86 87 .. attribute:: data 88 89 Optional opaque data associated to this file object: for example, this 90 could be used to store a per-client session ID. 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 105 .. abstractmethod:: register(fileobj, events, data=None) 106 107 Register a file object for selection, monitoring it for I/O events. 108 109 *fileobj* is the file object to monitor. It may either be an integer 110 file descriptor or an object with a ``fileno()`` method. 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 118 .. abstractmethod:: unregister(fileobj) 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 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). 129 130 .. method:: modify(fileobj, events, data=None) 131 132 Change a registered file object's monitored events or attached data. 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 142 .. abstractmethod:: select(timeout=None) 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 153 This returns a list of ``(key, events)`` tuples, one for each ready file 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 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 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 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 180 Return the key associated with a registered file object. 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 185 .. abstractmethod:: get_map() 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 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 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 229 .. versionadded:: 3.5 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 241 Examples 242 -------- 243 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) 278
