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
42Classes
43-------
44
45Classes hierarchy::
46
47   BaseSelector
48   +-- SelectSelector
49   +-- PollSelector
50   +-- EpollSelector
51   +-- DevpollSelector
52   +-- KqueueSelector
53
54
55In the following, *events* is a bitwise mask indicating which I/O events should
56be waited for on a given file object. It can be a combination of the modules
57constants 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
241Examples
242--------
243
244Here 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