rest25/library/select.rst => rest262/library/select.rst
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
9This module provides access to the :cfunc:`select` and :cfunc:`poll` functions
n10-available in most operating systems.  Note that on Windows, it only works for
n10+available in most operating systems, :cfunc:`epoll` available on Linux 2.5+ and
11-sockets; on other operating systems, it also works for other file types (in
11+:cfunc:`kqueue` available on most BSD.
12-particular, on Unix, it works on pipes).  It cannot be used on regular files to
12+Note that on Windows, it only works for sockets; on other operating systems,
13-determine whether a file has grown since it was last read.
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.
14
15The module defines the following:
16
17
18.. exception:: error
19
20   The exception raised when an error occurs.  The accompanying value is a pair
21   containing the numeric error code from :cdata:`errno` and the corresponding
22   string, as would be printed by the C function :cfunc:`perror`.
n25+ 
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
23
24
25.. function:: poll()
26
27   (Not supported by all operating systems.)  Returns a polling object, which
28   supports registering and unregistering file descriptors, and then polling them
29   for I/O events; see section :ref:`poll-objects` below for the methods supported
30   by polling objects.
31
32
n45+.. 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+ 
33-.. function:: select(iwtdowtd, ewtd[, timeout])
61+.. function:: select(rlist, wlist, xlist[, timeout])
34
35   This is a straightforward interface to the Unix :cfunc:`select` system call.
n36-   The first three arguments are sequences of 'waitable objects': either integers
n64+   The first three arguments are sequences of 'waitable objects': either
37-   representing file descriptors or objects with a parameterless method named
65+   integers representing file descriptors or objects with a parameterless method
38-   :meth:`fileno` returning such an integer.  The three sequences of waitable
66+   named :meth:`fileno` returning such an integer:
39-   objects are for input, output and 'exceptional conditions', respectively.  Empty
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+ 
40-   sequences are allowed, but acceptance of three empty sequences is platform-
73+   Empty sequences are allowed, but acceptance of three empty sequences is
41-   dependent. (It is known to work on Unix but not on Windows.)  The optional
74+   platform-dependent. (It is known to work on Unix but not on Windows.)  The
42-   *timeout* argument specifies a time-out as a floating point number in seconds.
75+   optional *timeout* argument specifies a time-out as a floating point number
43-   When the *timeout* argument is omitted the function blocks until at least one
76+   in seconds.  When the *timeout* argument is omitted the function blocks until
44-   file descriptor is ready.  A time-out value of zero specifies a poll and never
77+   at least one file descriptor is ready.  A time-out value of zero specifies a
45-   blocks.
78+   poll and never blocks.
46
47   The return value is a triple of lists of objects that are ready: subsets of the
48   first three arguments.  When the time-out is reached without a file descriptor
49   becoming ready, three empty lists are returned.
50
51   .. index::
52      single: socket() (in module socket)
53      single: popen() (in module os)
54
55   Among the acceptable object types in the sequences are Python file objects (e.g.
56   ``sys.stdin``, or objects returned by :func:`open` or :func:`os.popen`), socket
57   objects returned by :func:`socket.socket`.  You may also define a :dfn:`wrapper`
58   class yourself, as long as it has an appropriate :meth:`fileno` method (that
59   really returns a file descriptor, not just a random integer).
60
n61-   .. % 
62- 
63   .. note::
64
65      .. index:: single: WinSock
66
n67-      File objects on Windows are not acceptable, but sockets are.  On Windows, the
n98+      File objects on Windows are not acceptable, but sockets are.  On Windows,
68-      underlying :cfunc:`select` function is provided by the WinSock library, and does
99+      the underlying :cfunc:`select` function is provided by the WinSock
69-      not handle file descriptors that don't originate from 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)
70
71
72.. _poll-objects:
73
74Polling Objects
75---------------
76
77The :cfunc:`poll` system call, supported on most Unix systems, provides better
78scalability for network servers that service many, many clients at the same
79time. :cfunc:`poll` scales better because the system call only requires listing
80the file descriptors of interest, while :cfunc:`select` builds a bitmap, turns
81on bits for the fds of interest, and then afterward the whole bitmap has to be
82linearly scanned again. :cfunc:`select` is O(highest file descriptor), while
83:cfunc:`poll` is O(number of file descriptors).
84
85
n86-.. method:: XXX Class.register(fd[, eventmask])
n193+.. method:: poll.register(fd[, eventmask])
87
88   Register a file descriptor with the polling object.  Future calls to the
89   :meth:`poll` method will then check whether the file descriptor has any pending
90   I/O events.  *fd* can be either an integer, or an object with a :meth:`fileno`
91   method that returns an integer.  File objects implement :meth:`fileno`, so they
92   can also be used as the argument.
93
94   *eventmask* is an optional bitmask describing the type of events you want to
111   +-------------------+------------------------------------------+
112   | :const:`POLLNVAL` | Invalid request: descriptor not open     |
113   +-------------------+------------------------------------------+
114
115   Registering a file descriptor that's already registered is not an error, and has
116   the same effect as registering the descriptor exactly once.
117
118
n226+.. 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+ 
119-.. method:: XXX Class.unregister(fd)
236+.. method:: poll.unregister(fd)
120
121   Remove a file descriptor being tracked by a polling object.  Just like the
122   :meth:`register` method, *fd* can be an integer or an object with a
123   :meth:`fileno` method that returns an integer.
124
125   Attempting to remove a file descriptor that was never registered causes a
126   :exc:`KeyError` exception to be raised.
127
128
n129-.. method:: XXX Class.poll([timeout])
n246+.. method:: poll.poll([timeout])
130
131   Polls the set of registered file descriptors, and returns a possibly-empty list
132   containing ``(fd, event)`` 2-tuples for the descriptors that have events or
133   errors to report. *fd* is the file descriptor, and *event* is a bitmask with
134   bits set for the reported events for that descriptor --- :const:`POLLIN` for
135   waiting input, :const:`POLLOUT` to indicate that the descriptor can be written
136   to, and so forth. An empty list indicates that the call timed out and no file
137   descriptors had any events to report. If *timeout* is given, it specifies the
138   length of time in milliseconds which the system will wait for events before
139   returning. If *timeout* is omitted, negative, or :const:`None`, the call will
140   block until there is an event for this poll object.
141
t259+ 
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
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op