|
1 |
|
2 :mod:`select` --- Waiting for I/O completion |
|
3 ============================================ |
|
4 |
|
5 .. module:: select |
|
6 :synopsis: Wait for I/O completion on multiple streams. |
|
7 |
|
8 |
|
9 This module provides access to the :cfunc:`select` and :cfunc:`poll` functions |
|
10 available in most operating systems, :cfunc:`epoll` available on Linux 2.5+ and |
|
11 :cfunc:`kqueue` available on most BSD. |
|
12 Note that on Windows, it only works for sockets; on other operating systems, |
|
13 it also works for other file types (in particular, on Unix, it works on pipes). |
|
14 It cannot be used on regular files to determine whether a file has grown since |
|
15 it was last read. |
|
16 |
|
17 The module defines the following: |
|
18 |
|
19 |
|
20 .. exception:: error |
|
21 |
|
22 The exception raised when an error occurs. The accompanying value is a pair |
|
23 containing the numeric error code from :cdata:`errno` and the corresponding |
|
24 string, as would be printed by the C function :cfunc:`perror`. |
|
25 |
|
26 |
|
27 .. function:: epoll([sizehint=-1]) |
|
28 |
|
29 (Only supported on Linux 2.5.44 and newer.) Returns an edge polling object, |
|
30 which can be used as Edge or Level Triggered interface for I/O events; see |
|
31 section :ref:`epoll-objects` below for the methods supported by epolling |
|
32 objects. |
|
33 |
|
34 .. versionadded:: 2.6 |
|
35 |
|
36 |
|
37 .. function:: poll() |
|
38 |
|
39 (Not supported by all operating systems.) Returns a polling object, which |
|
40 supports registering and unregistering file descriptors, and then polling them |
|
41 for I/O events; see section :ref:`poll-objects` below for the methods supported |
|
42 by polling objects. |
|
43 |
|
44 |
|
45 .. function:: kqueue() |
|
46 |
|
47 (Only supported on BSD.) Returns a kernel queue object object; see section |
|
48 :ref:`kqueue-objects` below for the methods supported by kqueue objects. |
|
49 |
|
50 .. versionadded:: 2.6 |
|
51 |
|
52 |
|
53 .. function:: kevent(ident, filter=KQ_FILTER_READ, flags=KQ_ADD, fflags=0, data=0, udata=0) |
|
54 |
|
55 (Only supported on BSD.) Returns a kernel event object object; see section |
|
56 :ref:`kevent-objects` below for the methods supported by kqueue objects. |
|
57 |
|
58 .. versionadded:: 2.6 |
|
59 |
|
60 |
|
61 .. function:: select(rlist, wlist, xlist[, timeout]) |
|
62 |
|
63 This is a straightforward interface to the Unix :cfunc:`select` system call. |
|
64 The first three arguments are sequences of 'waitable objects': either |
|
65 integers representing file descriptors or objects with a parameterless method |
|
66 named :meth:`fileno` returning such an integer: |
|
67 |
|
68 * *rlist*: wait until ready for reading |
|
69 * *wlist*: wait until ready for writing |
|
70 * *xlist*: wait for an "exceptional condition" (see the manual page for what |
|
71 your system considers such a condition) |
|
72 |
|
73 Empty sequences are allowed, but acceptance of three empty sequences is |
|
74 platform-dependent. (It is known to work on Unix but not on Windows.) The |
|
75 optional *timeout* argument specifies a time-out as a floating point number |
|
76 in seconds. When the *timeout* argument is omitted the function blocks until |
|
77 at least one file descriptor is ready. A time-out value of zero specifies a |
|
78 poll and never blocks. |
|
79 |
|
80 The return value is a triple of lists of objects that are ready: subsets of the |
|
81 first three arguments. When the time-out is reached without a file descriptor |
|
82 becoming ready, three empty lists are returned. |
|
83 |
|
84 .. index:: |
|
85 single: socket() (in module socket) |
|
86 single: popen() (in module os) |
|
87 |
|
88 Among the acceptable object types in the sequences are Python file objects (e.g. |
|
89 ``sys.stdin``, or objects returned by :func:`open` or :func:`os.popen`), socket |
|
90 objects returned by :func:`socket.socket`. You may also define a :dfn:`wrapper` |
|
91 class yourself, as long as it has an appropriate :meth:`fileno` method (that |
|
92 really returns a file descriptor, not just a random integer). |
|
93 |
|
94 .. note:: |
|
95 |
|
96 .. index:: single: WinSock |
|
97 |
|
98 File objects on Windows are not acceptable, but sockets are. On Windows, |
|
99 the underlying :cfunc:`select` function is provided by the WinSock |
|
100 library, and does not handle file descriptors that don't originate from |
|
101 WinSock. |
|
102 |
|
103 |
|
104 .. _epoll-objects: |
|
105 |
|
106 Edge and Level Trigger Polling (epoll) Objects |
|
107 ---------------------------------------------- |
|
108 |
|
109 http://linux.die.net/man/4/epoll |
|
110 |
|
111 *eventmask* |
|
112 |
|
113 +-----------------------+-----------------------------------------------+ |
|
114 | Constant | Meaning | |
|
115 +=======================+===============================================+ |
|
116 | :const:`EPOLLIN` | Available for read | |
|
117 +-----------------------+-----------------------------------------------+ |
|
118 | :const:`EPOLLOUT` | Available for write | |
|
119 +-----------------------+-----------------------------------------------+ |
|
120 | :const:`EPOLLPRI` | Urgent data for read | |
|
121 +-----------------------+-----------------------------------------------+ |
|
122 | :const:`EPOLLERR` | Error condition happened on the assoc. fd | |
|
123 +-----------------------+-----------------------------------------------+ |
|
124 | :const:`EPOLLHUP` | Hang up happened on the assoc. fd | |
|
125 +-----------------------+-----------------------------------------------+ |
|
126 | :const:`EPOLLET` | Set Edge Trigger behavior, the default is | |
|
127 | | Level Trigger behavior | |
|
128 +-----------------------+-----------------------------------------------+ |
|
129 | :const:`EPOLLONESHOT` | Set one-shot behavior. After one event is | |
|
130 | | pulled out, the fd is internally disabled | |
|
131 +-----------------------+-----------------------------------------------+ |
|
132 | :const:`EPOLLRDNORM` | ??? | |
|
133 +-----------------------+-----------------------------------------------+ |
|
134 | :const:`EPOLLRDBAND` | ??? | |
|
135 +-----------------------+-----------------------------------------------+ |
|
136 | :const:`EPOLLWRNORM` | ??? | |
|
137 +-----------------------+-----------------------------------------------+ |
|
138 | :const:`EPOLLWRBAND` | ??? | |
|
139 +-----------------------+-----------------------------------------------+ |
|
140 | :const:`EPOLLMSG` | ??? | |
|
141 +-----------------------+-----------------------------------------------+ |
|
142 |
|
143 |
|
144 .. method:: epoll.close() |
|
145 |
|
146 Close the control file descriptor of the epoll object. |
|
147 |
|
148 |
|
149 .. method:: epoll.fileno() |
|
150 |
|
151 Return the file descriptor number of the control fd. |
|
152 |
|
153 |
|
154 .. method:: epoll.fromfd(fd) |
|
155 |
|
156 Create an epoll object from a given file descriptor. |
|
157 |
|
158 |
|
159 .. method:: epoll.register(fd[, eventmask]) |
|
160 |
|
161 Register a fd descriptor with the epoll object. |
|
162 |
|
163 |
|
164 .. method:: epoll.modify(fd, eventmask) |
|
165 |
|
166 Modify a register file descriptor. |
|
167 |
|
168 |
|
169 .. method:: epoll.unregister(fd) |
|
170 |
|
171 Remove a registered file descriptor from the epoll object. |
|
172 |
|
173 |
|
174 .. method:: epoll.poll([timeout=-1[, maxevents=-1]]) |
|
175 |
|
176 Wait for events. timeout in seconds (float) |
|
177 |
|
178 |
|
179 .. _poll-objects: |
|
180 |
|
181 Polling Objects |
|
182 --------------- |
|
183 |
|
184 The :cfunc:`poll` system call, supported on most Unix systems, provides better |
|
185 scalability for network servers that service many, many clients at the same |
|
186 time. :cfunc:`poll` scales better because the system call only requires listing |
|
187 the file descriptors of interest, while :cfunc:`select` builds a bitmap, turns |
|
188 on bits for the fds of interest, and then afterward the whole bitmap has to be |
|
189 linearly scanned again. :cfunc:`select` is O(highest file descriptor), while |
|
190 :cfunc:`poll` is O(number of file descriptors). |
|
191 |
|
192 |
|
193 .. method:: poll.register(fd[, eventmask]) |
|
194 |
|
195 Register a file descriptor with the polling object. Future calls to the |
|
196 :meth:`poll` method will then check whether the file descriptor has any pending |
|
197 I/O events. *fd* can be either an integer, or an object with a :meth:`fileno` |
|
198 method that returns an integer. File objects implement :meth:`fileno`, so they |
|
199 can also be used as the argument. |
|
200 |
|
201 *eventmask* is an optional bitmask describing the type of events you want to |
|
202 check for, and can be a combination of the constants :const:`POLLIN`, |
|
203 :const:`POLLPRI`, and :const:`POLLOUT`, described in the table below. If not |
|
204 specified, the default value used will check for all 3 types of events. |
|
205 |
|
206 +-------------------+------------------------------------------+ |
|
207 | Constant | Meaning | |
|
208 +===================+==========================================+ |
|
209 | :const:`POLLIN` | There is data to read | |
|
210 +-------------------+------------------------------------------+ |
|
211 | :const:`POLLPRI` | There is urgent data to read | |
|
212 +-------------------+------------------------------------------+ |
|
213 | :const:`POLLOUT` | Ready for output: writing will not block | |
|
214 +-------------------+------------------------------------------+ |
|
215 | :const:`POLLERR` | Error condition of some sort | |
|
216 +-------------------+------------------------------------------+ |
|
217 | :const:`POLLHUP` | Hung up | |
|
218 +-------------------+------------------------------------------+ |
|
219 | :const:`POLLNVAL` | Invalid request: descriptor not open | |
|
220 +-------------------+------------------------------------------+ |
|
221 |
|
222 Registering a file descriptor that's already registered is not an error, and has |
|
223 the same effect as registering the descriptor exactly once. |
|
224 |
|
225 |
|
226 .. method:: poll.modify(fd, eventmask) |
|
227 |
|
228 Modifies an already registered fd. This has the same effect as |
|
229 :meth:`register(fd, eventmask)`. Attempting to modify a file descriptor |
|
230 that was never registered causes an :exc:`IOError` exception with errno |
|
231 :const:`ENOENT` to be raised. |
|
232 |
|
233 .. versionadded:: 2.6 |
|
234 |
|
235 |
|
236 .. method:: poll.unregister(fd) |
|
237 |
|
238 Remove a file descriptor being tracked by a polling object. Just like the |
|
239 :meth:`register` method, *fd* can be an integer or an object with a |
|
240 :meth:`fileno` method that returns an integer. |
|
241 |
|
242 Attempting to remove a file descriptor that was never registered causes a |
|
243 :exc:`KeyError` exception to be raised. |
|
244 |
|
245 |
|
246 .. method:: poll.poll([timeout]) |
|
247 |
|
248 Polls the set of registered file descriptors, and returns a possibly-empty list |
|
249 containing ``(fd, event)`` 2-tuples for the descriptors that have events or |
|
250 errors to report. *fd* is the file descriptor, and *event* is a bitmask with |
|
251 bits set for the reported events for that descriptor --- :const:`POLLIN` for |
|
252 waiting input, :const:`POLLOUT` to indicate that the descriptor can be written |
|
253 to, and so forth. An empty list indicates that the call timed out and no file |
|
254 descriptors had any events to report. If *timeout* is given, it specifies the |
|
255 length of time in milliseconds which the system will wait for events before |
|
256 returning. If *timeout* is omitted, negative, or :const:`None`, the call will |
|
257 block until there is an event for this poll object. |
|
258 |
|
259 |
|
260 .. _kqueue-objects: |
|
261 |
|
262 Kqueue Objects |
|
263 -------------- |
|
264 |
|
265 .. method:: kqueue.close() |
|
266 |
|
267 Close the control file descriptor of the kqueue object. |
|
268 |
|
269 |
|
270 .. method:: kqueue.fileno() |
|
271 |
|
272 Return the file descriptor number of the control fd. |
|
273 |
|
274 |
|
275 .. method:: kqueue.fromfd(fd) |
|
276 |
|
277 Create a kqueue object from a given file descriptor. |
|
278 |
|
279 |
|
280 .. method:: kqueue.control(changelist, max_events[, timeout=None]) -> eventlist |
|
281 |
|
282 Low level interface to kevent |
|
283 |
|
284 - changelist must be an iterable of kevent object or None |
|
285 - max_events must be 0 or a positive integer |
|
286 - timeout in seconds (floats possible) |
|
287 |
|
288 |
|
289 .. _kevent-objects: |
|
290 |
|
291 Kevent Objects |
|
292 -------------- |
|
293 |
|
294 http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 |
|
295 |
|
296 .. attribute:: kevent.ident |
|
297 |
|
298 Value used to identify the event. The interpretation depends on the filter |
|
299 but it's usually the file descriptor. In the constructor ident can either |
|
300 be an int or an object with a fileno() function. kevent stores the integer |
|
301 internally. |
|
302 |
|
303 .. attribute:: kevent.filter |
|
304 |
|
305 Name of the kernel filter |
|
306 |
|
307 +---------------------------+---------------------------------------------+ |
|
308 | Constant | Meaning | |
|
309 +===========================+=============================================+ |
|
310 | :const:`KQ_FILTER_READ` | Takes a descriptor and returns whenever | |
|
311 | | there is data available to read | |
|
312 +---------------------------+---------------------------------------------+ |
|
313 | :const:`KQ_FILTER_WRITE` | Takes a descriptor and returns whenever | |
|
314 | | there is data available to read | |
|
315 +---------------------------+---------------------------------------------+ |
|
316 | :const:`KQ_FILTER_AIO` | AIO requests | |
|
317 +---------------------------+---------------------------------------------+ |
|
318 | :const:`KQ_FILTER_VNODE` | Returns when one or more of the requested | |
|
319 | | events watched in *fflag* occurs | |
|
320 +---------------------------+---------------------------------------------+ |
|
321 | :const:`KQ_FILTER_PROC` | Watch for events on a process id | |
|
322 +---------------------------+---------------------------------------------+ |
|
323 | :const:`KQ_FILTER_NETDEV` | Watch for events on a network device | |
|
324 | | [not available on Mac OS X] | |
|
325 +---------------------------+---------------------------------------------+ |
|
326 | :const:`KQ_FILTER_SIGNAL` | Returns whenever the watched signal is | |
|
327 | | delivered to the process | |
|
328 +---------------------------+---------------------------------------------+ |
|
329 | :const:`KQ_FILTER_TIMER` | Establishes an arbitrary timer | |
|
330 +---------------------------+---------------------------------------------+ |
|
331 |
|
332 .. attribute:: kevent.flags |
|
333 |
|
334 Filter action |
|
335 |
|
336 +---------------------------+---------------------------------------------+ |
|
337 | Constant | Meaning | |
|
338 +===========================+=============================================+ |
|
339 | :const:`KQ_EV_ADD` | Adds or modifies an event | |
|
340 +---------------------------+---------------------------------------------+ |
|
341 | :const:`KQ_EV_DELETE` | Removes an event from the queue | |
|
342 +---------------------------+---------------------------------------------+ |
|
343 | :const:`KQ_EV_ENABLE` | Permitscontrol() to returns the event | |
|
344 +---------------------------+---------------------------------------------+ |
|
345 | :const:`KQ_EV_DISABLE` | Disablesevent | |
|
346 +---------------------------+---------------------------------------------+ |
|
347 | :const:`KQ_EV_ONESHOT` | Removes event after first occurrence | |
|
348 +---------------------------+---------------------------------------------+ |
|
349 | :const:`KQ_EV_CLEAR` | Reset the state after an event is retrieved | |
|
350 +---------------------------+---------------------------------------------+ |
|
351 | :const:`KQ_EV_SYSFLAGS` | internal event | |
|
352 +---------------------------+---------------------------------------------+ |
|
353 | :const:`KQ_EV_FLAG1` | internal event | |
|
354 +---------------------------+---------------------------------------------+ |
|
355 | :const:`KQ_EV_EOF` | Filter specific EOF condition | |
|
356 +---------------------------+---------------------------------------------+ |
|
357 | :const:`KQ_EV_ERROR` | See return values | |
|
358 +---------------------------+---------------------------------------------+ |
|
359 |
|
360 |
|
361 .. attribute:: kevent.fflags |
|
362 |
|
363 Filter specific flags |
|
364 |
|
365 |
|
366 :const:`KQ_FILTER_READ` and :const:`KQ_FILTER_WRITE` filter flags |
|
367 |
|
368 +----------------------------+--------------------------------------------+ |
|
369 | Constant | Meaning | |
|
370 +============================+============================================+ |
|
371 | :const:`KQ_NOTE_LOWAT` | low water mark of a socket buffer | |
|
372 +----------------------------+--------------------------------------------+ |
|
373 |
|
374 |
|
375 :const:`KQ_FILTER_VNODE` filter flags |
|
376 |
|
377 +----------------------------+--------------------------------------------+ |
|
378 | Constant | Meaning | |
|
379 +============================+============================================+ |
|
380 | :const:`KQ_NOTE_DELETE` | *unlink()* was called | |
|
381 +----------------------------+--------------------------------------------+ |
|
382 | :const:`KQ_NOTE_WRITE` | a write occurred | |
|
383 +----------------------------+--------------------------------------------+ |
|
384 | :const:`KQ_NOTE_EXTEND` | the file was extended | |
|
385 +----------------------------+--------------------------------------------+ |
|
386 | :const:`KQ_NOTE_ATTRIB` | an attribute was changed | |
|
387 +----------------------------+--------------------------------------------+ |
|
388 | :const:`KQ_NOTE_LINK` | the link count has changed | |
|
389 +----------------------------+--------------------------------------------+ |
|
390 | :const:`KQ_NOTE_RENAME` | the file was renamed | |
|
391 +----------------------------+--------------------------------------------+ |
|
392 | :const:`KQ_NOTE_REVOKE` | access to the file was revoked | |
|
393 +----------------------------+--------------------------------------------+ |
|
394 |
|
395 |
|
396 :const:`KQ_FILTER_PROC` filter flags |
|
397 |
|
398 +----------------------------+--------------------------------------------+ |
|
399 | Constant | Meaning | |
|
400 +============================+============================================+ |
|
401 | :const:`KQ_NOTE_EXIT` | the process has exited | |
|
402 +----------------------------+--------------------------------------------+ |
|
403 | :const:`KQ_NOTE_FORK` | the process has called *fork()* | |
|
404 +----------------------------+--------------------------------------------+ |
|
405 | :const:`KQ_NOTE_EXEC` | the process has executed a new process | |
|
406 +----------------------------+--------------------------------------------+ |
|
407 | :const:`KQ_NOTE_PCTRLMASK` | internal filter flag | |
|
408 +----------------------------+--------------------------------------------+ |
|
409 | :const:`KQ_NOTE_PDATAMASK` | internal filter flag | |
|
410 +----------------------------+--------------------------------------------+ |
|
411 | :const:`KQ_NOTE_TRACK` | follow a process across *fork()* | |
|
412 +----------------------------+--------------------------------------------+ |
|
413 | :const:`KQ_NOTE_CHILD` | returned on the child process for | |
|
414 | | *NOTE_TRACK* | |
|
415 +----------------------------+--------------------------------------------+ |
|
416 | :const:`KQ_NOTE_TRACKERR` | unable to attach to a child | |
|
417 +----------------------------+--------------------------------------------+ |
|
418 |
|
419 :const:`KQ_FILTER_NETDEV` filter flags [not available on Mac OS X] |
|
420 |
|
421 +----------------------------+--------------------------------------------+ |
|
422 | Constant | Meaning | |
|
423 +============================+============================================+ |
|
424 | :const:`KQ_NOTE_LINKUP` | link is up | |
|
425 +----------------------------+--------------------------------------------+ |
|
426 | :const:`KQ_NOTE_LINKDOWN` | link is down | |
|
427 +----------------------------+--------------------------------------------+ |
|
428 | :const:`KQ_NOTE_LINKINV` | link state is invalid | |
|
429 +----------------------------+--------------------------------------------+ |
|
430 |
|
431 |
|
432 .. attribute:: kevent.data |
|
433 |
|
434 Filter specific data |
|
435 |
|
436 |
|
437 .. attribute:: kevent.udata |
|
438 |
|
439 User defined value |