Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 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 | |
| 10 | Introduction |
| 11 | ------------ |
| 12 | |
| 13 | This module allows high-level and efficient I/O multiplexing, built upon the |
| 14 | :mod:`select` module primitives. Users are encouraged to use this module |
| 15 | instead, unless they want precise control over the OS-level primitives used. |
| 16 | |
| 17 | It defines a :class:`BaseSelector` abstract base class, along with several |
| 18 | concrete implementations (:class:`KqueueSelector`, :class:`EpollSelector`...), |
| 19 | that can be used to wait for I/O readiness notification on multiple file |
| 20 | objects. In the following, "file object" refers to any object with a |
| 21 | :meth:`fileno()` method, or a raw file descriptor. See :term:`file object`. |
| 22 | |
| 23 | :class:`DefaultSelector` is an alias to the most efficient implementation |
| 24 | available on the current platform: this should be the default choice for most |
| 25 | users. |
| 26 | |
| 27 | .. note:: |
| 28 | The type of file objects supported depends on the platform: on Windows, |
| 29 | sockets are supported, but not pipes, whereas on Unix, both are supported |
| 30 | (some other types may be supported as well, such as fifos or special file |
| 31 | devices). |
| 32 | |
| 33 | .. seealso:: |
| 34 | |
| 35 | :mod:`select` |
| 36 | Low-level I/O multiplexing module. |
| 37 | |
| 38 | |
| 39 | Classes |
| 40 | ------- |
| 41 | |
| 42 | Classes hierarchy:: |
| 43 | |
| 44 | BaseSelector |
| 45 | +-- SelectSelector |
| 46 | +-- PollSelector |
| 47 | +-- EpollSelector |
| 48 | +-- KqueueSelector |
| 49 | |
| 50 | |
| 51 | In the following, *events* is a bitwise mask indicating which I/O events should |
| 52 | be waited for on a given file object. It can be a combination of the constants |
| 53 | below: |
| 54 | |
| 55 | +-----------------------+-----------------------------------------------+ |
| 56 | | Constant | Meaning | |
| 57 | +=======================+===============================================+ |
| 58 | | :const:`EVENT_READ` | Available for read | |
| 59 | +-----------------------+-----------------------------------------------+ |
| 60 | | :const:`EVENT_WRITE` | Available for write | |
| 61 | +-----------------------+-----------------------------------------------+ |
| 62 | |
| 63 | |
| 64 | .. class:: SelectorKey |
| 65 | |
| 66 | A :class:`SelectorKey` is a :class:`~collections.namedtuple` used to |
| 67 | associate a file object to its underlying file decriptor, selected event |
| 68 | mask and attached data. It is returned by several :class:`BaseSelector` |
| 69 | methods. |
| 70 | |
| 71 | .. attribute:: fileobj |
| 72 | |
| 73 | File object registered. |
| 74 | |
| 75 | .. attribute:: fd |
| 76 | |
| 77 | Underlying file descriptor. |
| 78 | |
| 79 | .. attribute:: events |
| 80 | |
| 81 | Events that must be waited for this file object. |
| 82 | |
| 83 | .. attribute:: data |
| 84 | |
| 85 | Optional opaque data associated to this file object: for example, this |
| 86 | could be used to store per-client session. |
| 87 | |
| 88 | |
| 89 | .. class:: BaseSelector |
| 90 | |
| 91 | A :class:`BaseSelector` is used to wait for I/O event readiness on multiple |
| 92 | file objects. It supports file stream registration, unregistration, and a |
| 93 | method to wait for I/O events on those streams, with an optional timeout. |
| 94 | It's an abstract base class, so cannot be instantiated. Use |
| 95 | :class:`DefaultSelector` instead, or one of :class:`SelectSelector`, |
| 96 | :class:`KqueueSelector` etc. if you want to specifically use an |
| 97 | implementation, and your platform supports it. |
| 98 | :class:`BaseSelector` and its concrete implementations support the |
| 99 | :term:`context manager` protocol. |
| 100 | |
| 101 | .. method:: register(fileobj, events, data=None) |
| 102 | |
| 103 | Register a file object for selection, monitoring it for I/O events. |
| 104 | |
| 105 | *fileobj* is the file object to monitor. |
| 106 | *events* is a bitwise mask of events to monitor. |
| 107 | *data* is an opaque object. |
| 108 | |
| 109 | This returns a new :class:`SelectorKey` instance, or raises a |
| 110 | :exc:`ValueError` in case of invalid event mask or file descriptor, or |
| 111 | :exc:`KeyError` if the file object is already registered. |
| 112 | |
| 113 | .. method:: unregister(fileobj) |
| 114 | |
| 115 | Unregister a file object from selection, removing it from monitoring. A |
| 116 | file object shall be unregistered prior to being closed. |
| 117 | |
| 118 | *fileobj* must be a file object previously registered. |
| 119 | |
| 120 | This returns the associated :class:`SelectorKey` instance, or raises a |
| 121 | :exc:`KeyError` if the file object is not registered. |
| 122 | |
| 123 | .. method:: modify(fileobj, events, data=None) |
| 124 | |
| 125 | Change a registered file object monitored events or attached data. |
| 126 | |
| 127 | This is equivalent to :meth:`BaseSelector.unregister(fileobj)` followed |
| 128 | by :meth:`BaseSelector.register(fileobj, events, data)`, except that it |
| 129 | can be implemented more efficiently. |
| 130 | |
| 131 | This returns a new :class:`SelectorKey` instance, or raises a |
| 132 | :exc:`ValueError` in case of invalid event mask or file descriptor, or |
| 133 | :exc:`KeyError` if the file object is not registered. |
| 134 | |
| 135 | .. method:: select(timeout=None) |
| 136 | |
| 137 | Wait until some registered file objects become ready, or the timeout |
| 138 | expires. |
| 139 | |
| 140 | If ``timeout > 0``, this specifies the maximum wait time, in seconds. |
| 141 | If ``timeout <= 0``, the call won't block, and will report the currently |
| 142 | ready file objects. |
| 143 | If *timeout* is ``None``, the call will block until a monitored file object |
| 144 | becomes ready. |
| 145 | |
| 146 | This returns a list of ``(key, events)`` tuple, one for each ready file |
| 147 | object. |
| 148 | |
| 149 | *key* is the :class:`SelectorKey` instance corresponding to a ready file |
| 150 | object. |
| 151 | *events* is a bitmask of events ready on this file object. |
| 152 | |
| 153 | .. method:: close() |
| 154 | |
| 155 | Close the selector. |
| 156 | |
| 157 | This must be called to make sure that any underlying resource is freed. |
| 158 | The selector shall not be used once it has been closed. |
| 159 | |
| 160 | .. method:: get_key(fileobj) |
| 161 | |
| 162 | Return the key associated to a registered file object. |
| 163 | |
| 164 | This returns the :class:`SelectorKey` instance associated to this file |
| 165 | object, or raises :exc:`KeyError` if the file object is not registered. |
| 166 | |
Charles-François Natali | 4574b49 | 2013-10-30 20:31:04 +0100 | [diff] [blame^] | 167 | .. method:: get_map() |
| 168 | |
| 169 | Return a mapping of file objects to selector keys. |
| 170 | |
| 171 | This returns a :class:`~collections.abc.Mapping` instance mapping |
| 172 | registered file objects to their associated :class:`SelectorKey` |
| 173 | instance. |
| 174 | |
Charles-François Natali | 243d8d8 | 2013-09-04 19:02:49 +0200 | [diff] [blame] | 175 | |
| 176 | .. class:: DefaultSelector() |
| 177 | |
| 178 | The default selector class, using the most efficient implementation |
| 179 | available on the current platform. This should be the default choice for |
| 180 | most users. |
| 181 | |
| 182 | |
| 183 | .. class:: SelectSelector() |
| 184 | |
| 185 | :func:`select.select`-based selector. |
| 186 | |
| 187 | |
| 188 | .. class:: PollSelector() |
| 189 | |
| 190 | :func:`select.poll`-based selector. |
| 191 | |
| 192 | |
| 193 | .. class:: EpollSelector() |
| 194 | |
| 195 | :func:`select.epoll`-based selector. |
| 196 | |
| 197 | .. method:: fileno() |
| 198 | |
| 199 | This returns the file descriptor used by the underlying |
| 200 | :func:`select.epoll` object. |
| 201 | |
| 202 | |
| 203 | .. class:: KqueueSelector() |
| 204 | |
| 205 | :func:`select.kqueue`-based selector. |
| 206 | |
| 207 | .. method:: fileno() |
| 208 | |
| 209 | This returns the file descriptor used by the underlying |
| 210 | :func:`select.kqueue` object. |
| 211 | |
| 212 | |
| 213 | Examples of selector usage:: |
| 214 | |
| 215 | >>> import selectors |
| 216 | >>> import socket |
| 217 | >>> |
| 218 | >>> s = selectors.DefaultSelector() |
| 219 | >>> r, w = socket.socketpair() |
| 220 | >>> |
| 221 | >>> s.register(r, selectors.EVENT_READ) |
| 222 | SelectorKey(fileobj=<socket.socket fd=4, family=1, type=1, proto=0>, fd=4, events=1, data=None) |
| 223 | >>> s.register(w, selectors.EVENT_WRITE) |
| 224 | SelectorKey(fileobj=<socket.socket fd=5, family=1, type=1, proto=0>, fd=5, events=2, data=None) |
| 225 | >>> |
| 226 | >>> print(s.select()) |
| 227 | [(SelectorKey(fileobj=<socket.socket fd=5, family=1, type=1, proto=0>, fd=5, events=2, data=None), 2)] |
| 228 | >>> |
| 229 | >>> for key, events in s.select(): |
| 230 | ... if events & selectors.EVENT_WRITE: |
| 231 | ... key.fileobj.send(b'spam') |
| 232 | ... |
| 233 | 4 |
| 234 | >>> for key, events in s.select(): |
| 235 | ... if events & selectors.EVENT_READ: |
| 236 | ... print(key.fileobj.recv(1024)) |
| 237 | ... |
| 238 | b'spam' |
| 239 | >>> s.close() |