1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
<span id="selectors-high-level-i-o-multiplexing"></span><h1>selectors — High-level I/O multiplexing</h1> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/selectors.py">Lib/selectors.py</a></p> <section id="introduction"> <h2>Introduction</h2> <p>This module allows high-level and efficient I/O multiplexing, built upon the <a class="reference internal" href="select#module-select" title="select: Wait for I/O completion on multiple streams."><code>select</code></a> module primitives. Users are encouraged to use this module instead, unless they want precise control over the OS-level primitives used.</p> <p>It defines a <a class="reference internal" href="#selectors.BaseSelector" title="selectors.BaseSelector"><code>BaseSelector</code></a> abstract base class, along with several concrete implementations (<a class="reference internal" href="#selectors.KqueueSelector" title="selectors.KqueueSelector"><code>KqueueSelector</code></a>, <a class="reference internal" href="#selectors.EpollSelector" title="selectors.EpollSelector"><code>EpollSelector</code></a>…), that can be used to wait for I/O readiness notification on multiple file objects. In the following, “file object” refers to any object with a <a class="reference internal" href="io#io.IOBase.fileno" title="io.IOBase.fileno"><code>fileno()</code></a> method, or a raw file descriptor. See <a class="reference internal" href="../glossary#term-file-object"><span class="xref std std-term">file object</span></a>.</p> <p><a class="reference internal" href="#selectors.DefaultSelector" title="selectors.DefaultSelector"><code>DefaultSelector</code></a> is an alias to the most efficient implementation available on the current platform: this should be the default choice for most users.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>The type of file objects supported depends on the platform: on Windows, sockets are supported, but not pipes, whereas on Unix, both are supported (some other types may be supported as well, such as fifos or special file devices).</p> </div> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt>
<code></code> <a class="reference internal" href="select#module-select" title="select: Wait for I/O completion on multiple streams."><code>select</code></a>
</dt>
<dd>
<p>Low-level I/O multiplexing module.</p> </dd> </dl> </div> <div class="availability docutils container"> <p><a class="reference internal" href="https://docs.python.org/3.12/library/intro.html#availability"><span class="std std-ref">Availability</span></a>: not Emscripten, not WASI.</p> <p>This module does not work or is not available on WebAssembly platforms <code>wasm32-emscripten</code> and <code>wasm32-wasi</code>. See <a class="reference internal" href="https://docs.python.org/3.12/library/intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a> for more information.</p> </div> </section> <section id="classes"> <h2>Classes</h2> <p>Classes hierarchy:</p> <pre data-language="python">BaseSelector
+-- SelectSelector
+-- PollSelector
+-- EpollSelector
+-- DevpollSelector
+-- KqueueSelector
</pre> <p>In the following, <em>events</em> is a bitwise mask indicating which I/O events should be waited for on a given file object. It can be a combination of the modules constants below:</p> <table class="docutils align-default"> <thead> <tr>
<th class="head"><p>Constant</p></th> <th class="head"><p>Meaning</p></th> </tr> </thead> <tr>
<td>
<dl class="py data"> <dt class="sig sig-object py" id="selectors.EVENT_READ">
<code>selectors.EVENT_READ</code> </dt> <dd></dd>
</dl> </td> <td><p>Available for read</p></td> </tr> <tr>
<td>
<dl class="py data"> <dt class="sig sig-object py" id="selectors.EVENT_WRITE">
<code>selectors.EVENT_WRITE</code> </dt> <dd></dd>
</dl> </td> <td><p>Available for write</p></td> </tr> </table> <dl class="py class"> <dt class="sig sig-object py" id="selectors.SelectorKey">
<code>class selectors.SelectorKey</code> </dt> <dd>
<p>A <a class="reference internal" href="#selectors.SelectorKey" title="selectors.SelectorKey"><code>SelectorKey</code></a> is a <a class="reference internal" href="collections#collections.namedtuple" title="collections.namedtuple"><code>namedtuple</code></a> used to associate a file object to its underlying file descriptor, selected event mask and attached data. It is returned by several <a class="reference internal" href="#selectors.BaseSelector" title="selectors.BaseSelector"><code>BaseSelector</code></a> methods.</p> <dl class="py attribute"> <dt class="sig sig-object py" id="selectors.SelectorKey.fileobj">
<code>fileobj</code> </dt> <dd>
<p>File object registered.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="selectors.SelectorKey.fd">
<code>fd</code> </dt> <dd>
<p>Underlying file descriptor.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="selectors.SelectorKey.events">
<code>events</code> </dt> <dd>
<p>Events that must be waited for on this file object.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="selectors.SelectorKey.data">
<code>data</code> </dt> <dd>
<p>Optional opaque data associated to this file object: for example, this could be used to store a per-client session ID.</p> </dd>
</dl> </dd>
</dl> <dl class="py class"> <dt class="sig sig-object py" id="selectors.BaseSelector">
<code>class selectors.BaseSelector</code> </dt> <dd>
<p>A <a class="reference internal" href="#selectors.BaseSelector" title="selectors.BaseSelector"><code>BaseSelector</code></a> is used to wait for I/O event readiness on multiple file objects. It supports file stream registration, unregistration, and a method to wait for I/O events on those streams, with an optional timeout. It’s an abstract base class, so cannot be instantiated. Use <a class="reference internal" href="#selectors.DefaultSelector" title="selectors.DefaultSelector"><code>DefaultSelector</code></a> instead, or one of <a class="reference internal" href="#selectors.SelectSelector" title="selectors.SelectSelector"><code>SelectSelector</code></a>, <a class="reference internal" href="#selectors.KqueueSelector" title="selectors.KqueueSelector"><code>KqueueSelector</code></a> etc. if you want to specifically use an implementation, and your platform supports it. <a class="reference internal" href="#selectors.BaseSelector" title="selectors.BaseSelector"><code>BaseSelector</code></a> and its concrete implementations support the <a class="reference internal" href="../glossary#term-context-manager"><span class="xref std std-term">context manager</span></a> protocol.</p> <dl class="py method"> <dt class="sig sig-object py" id="selectors.BaseSelector.register">
<code>abstractmethod register(fileobj, events, data=None)</code> </dt> <dd>
<p>Register a file object for selection, monitoring it for I/O events.</p> <p><em>fileobj</em> is the file object to monitor. It may either be an integer file descriptor or an object with a <code>fileno()</code> method. <em>events</em> is a bitwise mask of events to monitor. <em>data</em> is an opaque object.</p> <p>This returns a new <a class="reference internal" href="#selectors.SelectorKey" title="selectors.SelectorKey"><code>SelectorKey</code></a> instance, or raises a <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a> in case of invalid event mask or file descriptor, or <a class="reference internal" href="exceptions#KeyError" title="KeyError"><code>KeyError</code></a> if the file object is already registered.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="selectors.BaseSelector.unregister">
<code>abstractmethod unregister(fileobj)</code> </dt> <dd>
<p>Unregister a file object from selection, removing it from monitoring. A file object shall be unregistered prior to being closed.</p> <p><em>fileobj</em> must be a file object previously registered.</p> <p>This returns the associated <a class="reference internal" href="#selectors.SelectorKey" title="selectors.SelectorKey"><code>SelectorKey</code></a> instance, or raises a <a class="reference internal" href="exceptions#KeyError" title="KeyError"><code>KeyError</code></a> if <em>fileobj</em> is not registered. It will raise <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a> if <em>fileobj</em> is invalid (e.g. it has no <code>fileno()</code> method or its <code>fileno()</code> method has an invalid return value).</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="selectors.BaseSelector.modify">
<code>modify(fileobj, events, data=None)</code> </dt> <dd>
<p>Change a registered file object’s monitored events or attached data.</p> <p>This is equivalent to <code>BaseSelector.unregister(fileobj)</code> followed by <code>BaseSelector.register(fileobj, events, data)</code>, except that it can be implemented more efficiently.</p> <p>This returns a new <a class="reference internal" href="#selectors.SelectorKey" title="selectors.SelectorKey"><code>SelectorKey</code></a> instance, or raises a <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a> in case of invalid event mask or file descriptor, or <a class="reference internal" href="exceptions#KeyError" title="KeyError"><code>KeyError</code></a> if the file object is not registered.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="selectors.BaseSelector.select">
<code>abstractmethod select(timeout=None)</code> </dt> <dd>
<p>Wait until some registered file objects become ready, or the timeout expires.</p> <p>If <code>timeout > 0</code>, this specifies the maximum wait time, in seconds. If <code>timeout <= 0</code>, the call won’t block, and will report the currently ready file objects. If <em>timeout</em> is <code>None</code>, the call will block until a monitored file object becomes ready.</p> <p>This returns a list of <code>(key, events)</code> tuples, one for each ready file object.</p> <p><em>key</em> is the <a class="reference internal" href="#selectors.SelectorKey" title="selectors.SelectorKey"><code>SelectorKey</code></a> instance corresponding to a ready file object. <em>events</em> is a bitmask of events ready on this file object.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>This method can return before any file object becomes ready or the timeout has elapsed if the current process receives a signal: in this case, an empty list will be returned.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>The selector is now retried with a recomputed timeout when interrupted by a signal if the signal handler did not raise an exception (see <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0475/"><strong>PEP 475</strong></a> for the rationale), instead of returning an empty list of events before the timeout.</p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="selectors.BaseSelector.close">
<code>close()</code> </dt> <dd>
<p>Close the selector.</p> <p>This must be called to make sure that any underlying resource is freed. The selector shall not be used once it has been closed.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="selectors.BaseSelector.get_key">
<code>get_key(fileobj)</code> </dt> <dd>
<p>Return the key associated with a registered file object.</p> <p>This returns the <a class="reference internal" href="#selectors.SelectorKey" title="selectors.SelectorKey"><code>SelectorKey</code></a> instance associated to this file object, or raises <a class="reference internal" href="exceptions#KeyError" title="KeyError"><code>KeyError</code></a> if the file object is not registered.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="selectors.BaseSelector.get_map">
<code>abstractmethod get_map()</code> </dt> <dd>
<p>Return a mapping of file objects to selector keys.</p> <p>This returns a <a class="reference internal" href="collections.abc#collections.abc.Mapping" title="collections.abc.Mapping"><code>Mapping</code></a> instance mapping registered file objects to their associated <a class="reference internal" href="#selectors.SelectorKey" title="selectors.SelectorKey"><code>SelectorKey</code></a> instance.</p> </dd>
</dl> </dd>
</dl> <dl class="py class"> <dt class="sig sig-object py" id="selectors.DefaultSelector">
<code>class selectors.DefaultSelector</code> </dt> <dd>
<p>The default selector class, using the most efficient implementation available on the current platform. This should be the default choice for most users.</p> </dd>
</dl> <dl class="py class"> <dt class="sig sig-object py" id="selectors.SelectSelector">
<code>class selectors.SelectSelector</code> </dt> <dd>
<p><a class="reference internal" href="select#select.select" title="select.select"><code>select.select()</code></a>-based selector.</p> </dd>
</dl> <dl class="py class"> <dt class="sig sig-object py" id="selectors.PollSelector">
<code>class selectors.PollSelector</code> </dt> <dd>
<p><a class="reference internal" href="select#select.poll" title="select.poll"><code>select.poll()</code></a>-based selector.</p> </dd>
</dl> <dl class="py class"> <dt class="sig sig-object py" id="selectors.EpollSelector">
<code>class selectors.EpollSelector</code> </dt> <dd>
<p><a class="reference internal" href="select#select.epoll" title="select.epoll"><code>select.epoll()</code></a>-based selector.</p> <dl class="py method"> <dt class="sig sig-object py" id="selectors.EpollSelector.fileno">
<code>fileno()</code> </dt> <dd>
<p>This returns the file descriptor used by the underlying <a class="reference internal" href="select#select.epoll" title="select.epoll"><code>select.epoll()</code></a> object.</p> </dd>
</dl> </dd>
</dl> <dl class="py class"> <dt class="sig sig-object py" id="selectors.DevpollSelector">
<code>class selectors.DevpollSelector</code> </dt> <dd>
<p><a class="reference internal" href="select#select.devpoll" title="select.devpoll"><code>select.devpoll()</code></a>-based selector.</p> <dl class="py method"> <dt class="sig sig-object py" id="selectors.DevpollSelector.fileno">
<code>fileno()</code> </dt> <dd>
<p>This returns the file descriptor used by the underlying <a class="reference internal" href="select#select.devpoll" title="select.devpoll"><code>select.devpoll()</code></a> object.</p> </dd>
</dl> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.5.</span></p> </div> </dd>
</dl> <dl class="py class"> <dt class="sig sig-object py" id="selectors.KqueueSelector">
<code>class selectors.KqueueSelector</code> </dt> <dd>
<p><a class="reference internal" href="select#select.kqueue" title="select.kqueue"><code>select.kqueue()</code></a>-based selector.</p> <dl class="py method"> <dt class="sig sig-object py" id="selectors.KqueueSelector.fileno">
<code>fileno()</code> </dt> <dd>
<p>This returns the file descriptor used by the underlying <a class="reference internal" href="select#select.kqueue" title="select.kqueue"><code>select.kqueue()</code></a> object.</p> </dd>
</dl> </dd>
</dl> </section> <section id="examples"> <h2>Examples</h2> <p>Here is a simple echo server implementation:</p> <pre data-language="python">import selectors
import socket
sel = selectors.DefaultSelector()
def accept(sock, mask):
conn, addr = sock.accept() # Should be ready
print('accepted', conn, 'from', addr)
conn.setblocking(False)
sel.register(conn, selectors.EVENT_READ, read)
def read(conn, mask):
data = conn.recv(1000) # Should be ready
if data:
print('echoing', repr(data), 'to', conn)
conn.send(data) # Hope it won't block
else:
print('closing', conn)
sel.unregister(conn)
conn.close()
sock = socket.socket()
sock.bind(('localhost', 1234))
sock.listen(100)
sock.setblocking(False)
sel.register(sock, selectors.EVENT_READ, accept)
while True:
events = sel.select()
for key, mask in events:
callback = key.data
callback(key.fileobj, mask)
</pre> </section> <div class="_attribution">
<p class="_attribution-p">
© 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br>
<a href="https://docs.python.org/3.12/library/selectors.html" class="_attribution-link">https://docs.python.org/3.12/library/selectors.html</a>
</p>
</div>
|
