Debian Codegraph @

Doc/library/selectors.rst

raw
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:`~io.IOBase.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 .. include:: ../includes/wasm-notavail.rst
42
43 Classes
44 -------
45
46 Classes hierarchy::
47
48 BaseSelector
49 +-- SelectSelector
50 +-- PollSelector
51 +-- EpollSelector
52 +-- DevpollSelector
53 +-- KqueueSelector
54
55
56 In the following, *events* is a bitwise mask indicating which I/O events should
57 be waited for on a given file object. It can be a combination of the module's
58 constants below:
59
60 +-----------------------+-----------------------------------------------+
61 | Constant | Meaning |
62 +=======================+===============================================+
63 | .. data:: EVENT_READ | Available for read |
64 +-----------------------+-----------------------------------------------+
65 | .. data:: EVENT_WRITE | Available for write |
66 +-----------------------+-----------------------------------------------+
67
68
69 .. class:: SelectorKey
70
71 A :class:`SelectorKey` is a :class:`~collections.namedtuple` used to
72 associate a file object to its underlying file descriptor, selected event
73 mask and attached data. It is returned by several :class:`BaseSelector`
74 methods.
75
76 .. attribute:: fileobj
77
78 File object registered.
79
80 .. attribute:: fd
81
82 Underlying file descriptor.
83
84 .. attribute:: events
85
86 Events that must be waited for on this file object.
87
88 .. attribute:: data
89
90 Optional opaque data associated to this file object: for example, this
91 could be used to store a per-client session ID.
92
93
94 .. class:: BaseSelector
95
96 A :class:`BaseSelector` is used to wait for I/O event readiness on multiple
97 file objects. It supports file stream registration, unregistration, and a
98 method to wait for I/O events on those streams, with an optional timeout.
99 It's an abstract base class, so cannot be instantiated. Use
100 :class:`DefaultSelector` instead, or one of :class:`SelectSelector`,
101 :class:`KqueueSelector` etc. if you want to specifically use an
102 implementation, and your platform supports it.
103 :class:`BaseSelector` and its concrete implementations support the
104 :term:`context manager` protocol.
105
106 .. method:: register(fileobj, events, data=None)
107 :abstractmethod:
108
109 Register a file object for selection, monitoring it for I/O events.
110
111 *fileobj* is the file object to monitor. It may either be an integer
112 file descriptor or an object with a ``fileno()`` method.
113 *events* is a bitwise mask of events to monitor.
114 *data* is an opaque object.
115
116 This returns a new :class:`SelectorKey` instance, or raises a
117 :exc:`ValueError` in case of invalid event mask or file descriptor, or
118 :exc:`KeyError` if the file object is already registered.
119
120 .. method:: unregister(fileobj)
121 :abstractmethod:
122
123 Unregister a file object from selection, removing it from monitoring. A
124 file object shall be unregistered prior to being closed.
125
126 *fileobj* must be a file object previously registered.
127
128 This returns the associated :class:`SelectorKey` instance, or raises a
129 :exc:`KeyError` if *fileobj* is not registered. It will raise
130 :exc:`ValueError` if *fileobj* is invalid (e.g. it has no ``fileno()``
131 method or its ``fileno()`` method has an invalid return value).
132
133 .. method:: modify(fileobj, events, data=None)
134
135 Change a registered file object's monitored events or attached data.
136
137 This is equivalent to ``BaseSelector.unregister(fileobj)`` followed
138 by ``BaseSelector.register(fileobj, events, data)``, except that it
139 can be implemented more efficiently.
140
141 This returns a new :class:`SelectorKey` instance, or raises a
142 :exc:`ValueError` in case of invalid event mask or file descriptor, or
143 :exc:`KeyError` if the file object is not registered.
144
145 .. method:: select(timeout=None)
146 :abstractmethod:
147
148 Wait until some registered file objects become ready, or the timeout
149 expires.
150
151 If ``timeout > 0``, this specifies the maximum wait time, in seconds.
152 If ``timeout <= 0``, the call won't block, and will report the currently
153 ready file objects.
154 If *timeout* is ``None``, the call will block until a monitored file object
155 becomes ready.
156
157 This returns a list of ``(key, events)`` tuples, one for each ready file
158 object.
159
160 *key* is the :class:`SelectorKey` instance corresponding to a ready file
161 object.
162 *events* is a bitmask of events ready on this file object.
163
164 .. note::
165 This method can return before any file object becomes ready or the
166 timeout has elapsed if the current process receives a signal: in this
167 case, an empty list will be returned.
168
169 .. versionchanged:: 3.5
170 The selector is now retried with a recomputed timeout when interrupted
171 by a signal if the signal handler did not raise an exception (see
172 :pep:`475` for the rationale), instead of returning an empty list
173 of events before the timeout.
174
175 .. method:: close()
176
177 Close the selector.
178
179 This must be called to make sure that any underlying resource is freed.
180 The selector shall not be used once it has been closed.
181
182 .. method:: get_key(fileobj)
183
184 Return the key associated with a registered file object.
185
186 This returns the :class:`SelectorKey` instance associated to this file
187 object, or raises :exc:`KeyError` if the file object is not registered.
188
189 .. method:: get_map()
190 :abstractmethod:
191
192 Return a mapping of file objects to selector keys.
193
194 This returns a :class:`~collections.abc.Mapping` instance mapping
195 registered file objects to their associated :class:`SelectorKey`
196 instance.
197
198
199 .. class:: DefaultSelector()
200
201 The default selector class, using the most efficient implementation
202 available on the current platform. This should be the default choice for
203 most users.
204
205
206 .. class:: SelectSelector()
207
208 :func:`select.select`-based selector.
209
210
211 .. class:: PollSelector()
212
213 :func:`select.poll`-based selector.
214
215
216 .. class:: EpollSelector()
217
218 :func:`select.epoll`-based selector.
219
220 .. method:: fileno()
221
222 This returns the file descriptor used by the underlying
223 :func:`select.epoll` object.
224
225 .. class:: DevpollSelector()
226
227 :func:`select.devpoll`-based selector.
228
229 .. method:: fileno()
230
231 This returns the file descriptor used by the underlying
232 :func:`select.devpoll` object.
233
234 .. versionadded:: 3.5
235
236 .. class:: KqueueSelector()
237
238 :func:`select.kqueue`-based selector.
239
240 .. method:: fileno()
241
242 This returns the file descriptor used by the underlying
243 :func:`select.kqueue` object.
244
245
246 Examples
247 --------
248
249 Here is a simple echo server implementation::
250
251 import selectors
252 import socket
253
254 sel = selectors.DefaultSelector()
255
256 def accept(sock, mask):
257 conn, addr = sock.accept() # Should be ready
258 print('accepted', conn, 'from', addr)
259 conn.setblocking(False)
260 sel.register(conn, selectors.EVENT_READ, read)
261
262 def read(conn, mask):
263 data = conn.recv(1000) # Should be ready
264 if data:
265 print('echoing', repr(data), 'to', conn)
266 conn.send(data) # Hope it won't block
267 else:
268 print('closing', conn)
269 sel.unregister(conn)
270 conn.close()
271
272 sock = socket.socket()
273 sock.bind(('localhost', 1234))
274 sock.listen(100)
275 sock.setblocking(False)
276 sel.register(sock, selectors.EVENT_READ, accept)
277
278 while True:
279 events = sel.select()
280 for key, mask in events:
281 callback = key.data
282 callback(key.fileobj, mask)