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
13Introduction
14------------
15
16This module allows high-level and efficient I/O multiplexing, built upon the
17:mod:`select` module primitives. Users are encouraged to use this module
18instead, unless they want precise control over the OS-level primitives used.
19
20It defines a :class:`BaseSelector` abstract base class, along with several
21concrete implementations (:class:`KqueueSelector`, :class:`EpollSelector`...),
22that can be used to wait for I/O readiness notification on multiple file
23objects. 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
27available on the current platform: this should be the default choice for most
28users.
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
43Classes
44-------
45
46Classes hierarchy::
47
48   BaseSelector
49   +-- SelectSelector
50   +-- PollSelector
51   +-- EpollSelector
52   +-- DevpollSelector
53   +-- KqueueSelector
54
55
56In the following, *events* is a bitwise mask indicating which I/O events should
57be waited for on a given file object. It can be a combination of the modules
58constants below:
59
60   +-----------------------+-----------------------------------------------+
61   | Constant              | Meaning                                       |
62   +=======================+===============================================+
63   | :const:`EVENT_READ`   | Available for read                            |
64   +-----------------------+-----------------------------------------------+
65   | :const:`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   .. abstractmethod:: register(fileobj, events, data=None)
107
108      Register a file object for selection, monitoring it for I/O events.
109
110      *fileobj* is the file object to monitor.  It may either be an integer
111      file descriptor or an object with a ``fileno()`` method.
112      *events* is a bitwise mask of events to monitor.
113      *data* is an opaque object.
114
115      This returns a new :class:`SelectorKey` instance, or raises a
116      :exc:`ValueError` in case of invalid event mask or file descriptor, or
117      :exc:`KeyError` if the file object is already registered.
118
119   .. abstractmethod:: unregister(fileobj)
120
121      Unregister a file object from selection, removing it from monitoring. A
122      file object shall be unregistered prior to being closed.
123
124      *fileobj* must be a file object previously registered.
125
126      This returns the associated :class:`SelectorKey` instance, or raises a
127      :exc:`KeyError` if *fileobj* is not registered.  It will raise
128      :exc:`ValueError` if *fileobj* is invalid (e.g. it has no ``fileno()``
129      method or its ``fileno()`` method has an invalid return value).
130
131   .. method:: modify(fileobj, events, data=None)
132
133      Change a registered file object's monitored events or attached data.
134
135      This is equivalent to :meth:`BaseSelector.unregister(fileobj)` followed
136      by :meth:`BaseSelector.register(fileobj, events, data)`, except that it
137      can be implemented more efficiently.
138
139      This returns a new :class:`SelectorKey` instance, or raises a
140      :exc:`ValueError` in case of invalid event mask or file descriptor, or
141      :exc:`KeyError` if the file object is not registered.
142
143   .. abstractmethod:: select(timeout=None)
144
145      Wait until some registered file objects become ready, or the timeout
146      expires.
147
148      If ``timeout > 0``, this specifies the maximum wait time, in seconds.
149      If ``timeout <= 0``, the call won't block, and will report the currently
150      ready file objects.
151      If *timeout* is ``None``, the call will block until a monitored file object
152      becomes ready.
153
154      This returns a list of ``(key, events)`` tuples, one for each ready file
155      object.
156
157      *key* is the :class:`SelectorKey` instance corresponding to a ready file
158      object.
159      *events* is a bitmask of events ready on this file object.
160
161      .. note::
162          This method can return before any file object becomes ready or the
163          timeout has elapsed if the current process receives a signal: in this
164          case, an empty list will be returned.
165
166      .. versionchanged:: 3.5
167         The selector is now retried with a recomputed timeout when interrupted
168         by a signal if the signal handler did not raise an exception (see
169         :pep:`475` for the rationale), instead of returning an empty list
170         of events before the timeout.
171
172   .. method:: close()
173
174      Close the selector.
175
176      This must be called to make sure that any underlying resource is freed.
177      The selector shall not be used once it has been closed.
178
179   .. method:: get_key(fileobj)
180
181      Return the key associated with a registered file object.
182
183      This returns the :class:`SelectorKey` instance associated to this file
184      object, or raises :exc:`KeyError` if the file object is not registered.
185
186   .. abstractmethod:: get_map()
187
188      Return a mapping of file objects to selector keys.
189
190      This returns a :class:`~collections.abc.Mapping` instance mapping
191      registered file objects to their associated :class:`SelectorKey`
192      instance.
193
194
195.. class:: DefaultSelector()
196
197   The default selector class, using the most efficient implementation
198   available on the current platform. This should be the default choice for
199   most users.
200
201
202.. class:: SelectSelector()
203
204   :func:`select.select`-based selector.
205
206
207.. class:: PollSelector()
208
209   :func:`select.poll`-based selector.
210
211
212.. class:: EpollSelector()
213
214   :func:`select.epoll`-based selector.
215
216   .. method:: fileno()
217
218      This returns the file descriptor used by the underlying
219      :func:`select.epoll` object.
220
221.. class:: DevpollSelector()
222
223   :func:`select.devpoll`-based selector.
224
225   .. method:: fileno()
226
227      This returns the file descriptor used by the underlying
228      :func:`select.devpoll` object.
229
230   .. versionadded:: 3.5
231
232.. class:: KqueueSelector()
233
234   :func:`select.kqueue`-based selector.
235
236   .. method:: fileno()
237
238      This returns the file descriptor used by the underlying
239      :func:`select.kqueue` object.
240
241
242Examples
243--------
244
245Here is a simple echo server implementation::
246
247   import selectors
248   import socket
249
250   sel = selectors.DefaultSelector()
251
252   def accept(sock, mask):
253       conn, addr = sock.accept()  # Should be ready
254       print('accepted', conn, 'from', addr)
255       conn.setblocking(False)
256       sel.register(conn, selectors.EVENT_READ, read)
257
258   def read(conn, mask):
259       data = conn.recv(1000)  # Should be ready
260       if data:
261           print('echoing', repr(data), 'to', conn)
262           conn.send(data)  # Hope it won't block
263       else:
264           print('closing', conn)
265           sel.unregister(conn)
266           conn.close()
267
268   sock = socket.socket()
269   sock.bind(('localhost', 1234))
270   sock.listen(100)
271   sock.setblocking(False)
272   sel.register(sock, selectors.EVENT_READ, accept)
273
274   while True:
275       events = sel.select()
276       for key, mask in events:
277           callback = key.data
278           callback(key.fileobj, mask)
279