Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 243d8d8

Browse files
cf-natalicf-natali
committed
Issue #16853: Add new selectors module.
1 parent af722bf commit 243d8d8

6 files changed

Lines changed: 1033 additions & 3 deletions

File tree

‎Doc/library/concurrency.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ multitasking). Here's an overview:
2121
sched.rst
2222
queue.rst
2323
select.rst
24+
selectors.rst
2425

2526

2627
The following are support modules for some of the above services:

‎Doc/library/selectors.rst‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
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+
167+
168+
.. class:: DefaultSelector()
169+
170+
The default selector class, using the most efficient implementation
171+
available on the current platform. This should be the default choice for
172+
most users.
173+
174+
175+
.. class:: SelectSelector()
176+
177+
:func:`select.select`-based selector.
178+
179+
180+
.. class:: PollSelector()
181+
182+
:func:`select.poll`-based selector.
183+
184+
185+
.. class:: EpollSelector()
186+
187+
:func:`select.epoll`-based selector.
188+
189+
.. method:: fileno()
190+
191+
This returns the file descriptor used by the underlying
192+
:func:`select.epoll` object.
193+
194+
195+
.. class:: KqueueSelector()
196+
197+
:func:`select.kqueue`-based selector.
198+
199+
.. method:: fileno()
200+
201+
This returns the file descriptor used by the underlying
202+
:func:`select.kqueue` object.
203+
204+
205+
Examples of selector usage::
206+
207+
>>> import selectors
208+
>>> import socket
209+
>>>
210+
>>> s = selectors.DefaultSelector()
211+
>>> r, w = socket.socketpair()
212+
>>>
213+
>>> s.register(r, selectors.EVENT_READ)
214+
SelectorKey(fileobj=<socket.socket fd=4, family=1, type=1, proto=0>, fd=4, events=1, data=None)
215+
>>> s.register(w, selectors.EVENT_WRITE)
216+
SelectorKey(fileobj=<socket.socket fd=5, family=1, type=1, proto=0>, fd=5, events=2, data=None)
217+
>>>
218+
>>> print(s.select())
219+
[(SelectorKey(fileobj=<socket.socket fd=5, family=1, type=1, proto=0>, fd=5, events=2, data=None), 2)]
220+
>>>
221+
>>> for key, events in s.select():
222+
... if events & selectors.EVENT_WRITE:
223+
... key.fileobj.send(b'spam')
224+
...
225+
4
226+
>>> for key, events in s.select():
227+
... if events & selectors.EVENT_READ:
228+
... print(key.fileobj.recv(1024))
229+
...
230+
b'spam'
231+
>>> s.close()

‎Doc/whatsnew/3.4.rst‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -174,10 +174,11 @@ Some smaller changes made to the core Python language are:
174174
New Modules
175175
===========
176176

177-
.. module name
178-
.. -----------
177+
selectors
178+
---------
179179

180-
* None yet.
180+
The new :mod:`selectors` module allows high-level and efficient I/O
181+
multiplexing, built upon the :mod:`select` module primitives.
181182

182183

183184
Improved Modules

0 commit comments

Comments
 (0)