linuxport: Merging in the fruits of my labors (Python VFS)
[xbmc:xbmc-antiquated.git] / xbmc / lib / libPython / Python / Doc / lib / libselect.tex
1 \section{\module{select} ---
2          Waiting for I/O completion}
3
4 \declaremodule{builtin}{select}
5 \modulesynopsis{Wait for I/O completion on multiple streams.}
6
7
8 This module provides access to the \cfunction{select()}
9 and \cfunction{poll()} functions
10 available in most operating systems.  Note that on Windows, it only
11 works for sockets; on other operating systems, it also works for other
12 file types (in particular, on \UNIX, it works on pipes).  It cannot
13 be used on regular files to determine whether a file has grown since
14 it was last read.
15
16 The module defines the following:
17
18 \begin{excdesc}{error}
19 The exception raised when an error occurs.  The accompanying value is
20 a pair containing the numeric error code from \cdata{errno} and the
21 corresponding string, as would be printed by the \C{} function
22 \cfunction{perror()}.
23 \end{excdesc}
24
25 \begin{funcdesc}{poll}{}
26 (Not supported by all operating systems.)  Returns a polling object,
27 which supports registering and unregistering file descriptors, and
28 then polling them for I/O events;
29 see section~\ref{poll-objects} below for the methods supported by
30 polling objects.
31 \end{funcdesc}
32
33 \begin{funcdesc}{select}{iwtd, owtd, ewtd\optional{, timeout}}
34 This is a straightforward interface to the \UNIX{} \cfunction{select()}
35 system call.  The first three arguments are sequences of `waitable
36 objects': either integers representing file descriptors or
37 objects with a parameterless method named \method{fileno()} returning
38 such an integer.  The three sequences of waitable objects are for input,
39 output and `exceptional conditions', respectively.  Empty sequences are
40 allowed, but acceptance of three empty sequences is platform-dependent.
41 (It is known to work on \UNIX{} but not on Windows.)  The optional
42 \var{timeout} argument specifies a time-out as a floating point number
43 in seconds.  When the \var{timeout} argument is omitted the function
44 blocks until at least one file descriptor is ready.  A time-out value
45 of zero specifies a poll and never blocks.
46
47 The return value is a triple of lists of objects that are ready:
48 subsets of the first three arguments.  When the time-out is reached
49 without a file descriptor becoming ready, three empty lists are
50 returned.
51
52 Among the acceptable object types in the sequences are Python file
53 objects (e.g. \code{sys.stdin}, or objects returned by
54 \function{open()} or \function{os.popen()}), socket objects
55 returned by \function{socket.socket()}.%
56 \withsubitem{(in module socket)}{\ttindex{socket()}}
57 \withsubitem{(in module os)}{\ttindex{popen()}}
58 You may also define a \dfn{wrapper} class yourself, as long as it has
59 an appropriate \method{fileno()} method (that really returns a file
60 descriptor, not just a random integer).
61 \note{File objects on Windows are not acceptable, but sockets
62 are.\index{WinSock}  On Windows, the underlying \cfunction{select()}
63 function is provided by the WinSock library, and does not handle file
64 descriptors that don't originate from WinSock.}
65 \end{funcdesc}
66
67 \subsection{Polling Objects
68             \label{poll-objects}}
69
70 The \cfunction{poll()} system call, supported on most \UNIX{} systems,
71 provides better scalability for network servers that service many,
72 many clients at the same time.
73 \cfunction{poll()} scales better because the system call only
74 requires listing the file descriptors of interest, while \cfunction{select()}
75 builds a bitmap, turns on bits for the fds of interest, and then
76 afterward the whole bitmap has to be linearly scanned again.
77 \cfunction{select()} is O(highest file descriptor), while
78 \cfunction{poll()} is O(number of file descriptors).
79
80 \begin{methoddesc}{register}{fd\optional{, eventmask}}
81 Register a file descriptor with the polling object.  Future calls to
82 the \method{poll()} method will then check whether the file descriptor
83 has any pending I/O events.  \var{fd} can be either an integer, or an
84 object with a \method{fileno()} method that returns an integer.  File
85 objects implement
86 \method{fileno()}, so they can also be used as the argument.
87
88 \var{eventmask} is an optional bitmask describing the type of events you
89 want to check for, and can be a combination of the constants
90 \constant{POLLIN}, \constant{POLLPRI}, and \constant{POLLOUT},
91 described in the table below.  If not specified, the default value
92 used will check for all 3 types of events.
93
94 \begin{tableii}{l|l}{constant}{Constant}{Meaning}
95   \lineii{POLLIN}{There is data to read}
96   \lineii{POLLPRI}{There is urgent data to read}
97   \lineii{POLLOUT}{Ready for output: writing will not block}
98   \lineii{POLLERR}{Error condition of some sort}
99   \lineii{POLLHUP}{Hung up}
100   \lineii{POLLNVAL}{Invalid request: descriptor not open}
101 \end{tableii}
102
103 Registering a file descriptor that's already registered is not an
104 error, and has the same effect as registering the descriptor exactly
105 once.
106 \end{methoddesc}
107
108 \begin{methoddesc}{unregister}{fd}
109 Remove a file descriptor being tracked by a polling object.  Just like
110 the \method{register()} method, \var{fd} can be an integer or an
111 object with a \method{fileno()} method that returns an integer.
112
113 Attempting to remove a file descriptor that was never registered
114 causes a \exception{KeyError} exception to be raised.
115 \end{methoddesc}
116
117 \begin{methoddesc}{poll}{\optional{timeout}}
118 Polls the set of registered file descriptors, and returns a
119 possibly-empty list containing \code{(\var{fd}, \var{event})} 2-tuples
120 for the descriptors that have events or errors to report.
121 \var{fd} is the file descriptor, and \var{event} is a bitmask
122 with bits set for the reported events for that descriptor
123 --- \constant{POLLIN} for waiting input,
124 \constant{POLLOUT} to indicate that the descriptor can be written to, and
125 so forth.
126 An empty list indicates that the call timed out and no file
127 descriptors had any events to report.
128 If \var{timeout} is given, it specifies the length of time in
129 milliseconds which the system will wait for events before returning.
130 If \var{timeout} is omitted, negative, or \constant{None}, the call will
131 block until there is an event for this poll object.
132 \end{methoddesc}