\section{\module{select} ---         Waiting for I/O completion} \declaremodule{builtin}{select}\modulesynopsis{Wait for I/O completion on multiple streams.}  This module provides access to the \cfunction{select()}and \cfunction{poll()} functionsavailable in most operating systems.  Note that on Windows, it onlyworks for sockets; on other operating systems, it also works for otherfile types (in particular, on \UNIX, it works on pipes).  It cannotbe used on regular files to determine whether a file has grown sinceit was last read. The module defines the following: \begin{excdesc}{error}The exception raised when an error occurs.  The accompanying value isa pair containing the numeric error code from \cdata{errno} and thecorresponding string, as would be printed by the \C{} function\cfunction{perror()}.\end{excdesc} \begin{funcdesc}{poll}{}(Not supported by all operating systems.)  Returns a polling object,which supports registering and unregistering file descriptors, andthen polling them for I/O events;see section~\ref{poll-objects} below for the methods supported bypolling objects.\end{funcdesc} \begin{funcdesc}{select}{iwtd, owtd, ewtd\optional{, timeout}}This is a straightforward interface to the \UNIX{} \cfunction{select()}system call.  The first three arguments are sequences of `waitableobjects': either integers representing file descriptors orobjects with a parameterless method named \method{fileno()} returningsuch an integer.  The three sequences of waitable objects are for input,output and `exceptional conditions', respectively.  Empty sequences areallowed, but acceptance of three empty sequences is platform-dependent.(It is known to work on \UNIX{} but not on Windows.)  The optional\var{timeout} argument specifies a time-out as a floating point numberin seconds.  When the \var{timeout} argument is omitted the functionblocks until at least one file descriptor is ready.  A time-out valueof zero specifies a poll and never blocks. The return value is a triple of lists of objects that are ready:subsets of the first three arguments.  When the time-out is reachedwithout a file descriptor becoming ready, three empty lists arereturned. Among the acceptable object types in the sequences are Python fileobjects (e.g. \code{sys.stdin}, or objects returned by\function{open()} or \function{os.popen()}), socket objectsreturned by \function{socket.socket()}.%\withsubitem{(in module socket)}{\ttindex{socket()}}\withsubitem{(in module os)}{\ttindex{popen()}}You may also define a \dfn{wrapper} class yourself, as long as it hasan appropriate \method{fileno()} method (that really returns a filedescriptor, not just a random integer).\note{File objects on Windows are not acceptable, but socketsare.\index{WinSock}  On Windows, the underlying \cfunction{select()}function is provided by the WinSock library, and does not handle filedescriptors that don't originate from WinSock.}\end{funcdesc} \subsection{Polling Objects            \label{poll-objects}} The \cfunction{poll()} system call, supported on most \UNIX{} systems,provides better scalability for network servers that service many,many clients at the same time.\cfunction{poll()} scales better because the system call onlyrequires listing the file descriptors of interest, while \cfunction{select()}builds a bitmap, turns on bits for the fds of interest, and thenafterward the whole bitmap has to be linearly scanned again.\cfunction{select()} is O(highest file descriptor), while\cfunction{poll()} is O(number of file descriptors). \begin{methoddesc}{register}{fd\optional{, eventmask}}Register a file descriptor with the polling object.  Future calls tothe \method{poll()} method will then check whether the file descriptorhas any pending I/O events.  \var{fd} can be either an integer, or anobject with a \method{fileno()} method that returns an integer.  Fileobjects implement\method{fileno()}, so they can also be used as the argument. \var{eventmask} is an optional bitmask describing the type of events youwant to check for, and can be a combination of the constants\constant{POLLIN}, \constant{POLLPRI}, and \constant{POLLOUT},described in the table below.  If not specified, the default valueused will check for all 3 types of events. \begin{tableii}{l|l}{constant}{Constant}{Meaning}  \lineii{POLLIN}{There is data to read}  \lineii{POLLPRI}{There is urgent data to read}  \lineii{POLLOUT}{Ready for output: writing will not block}  \lineii{POLLERR}{Error condition of some sort}  \lineii{POLLHUP}{Hung up}  \lineii{POLLNVAL}{Invalid request: descriptor not open}\end{tableii} Registering a file descriptor that's already registered is not anerror, and has the same effect as registering the descriptor exactlyonce.\end{methoddesc} \begin{methoddesc}{unregister}{fd}Remove a file descriptor being tracked by a polling object.  Just likethe \method{register()} method, \var{fd} can be an integer or anobject with a \method{fileno()} method that returns an integer. Attempting to remove a file descriptor that was never registeredcauses a \exception{KeyError} exception to be raised.\end{methoddesc} \begin{methoddesc}{poll}{\optional{timeout}}Polls the set of registered file descriptors, and returns apossibly-empty list containing \code{(\var{fd}, \var{event})} 2-tuplesfor the descriptors that have events or errors to report.\var{fd} is the file descriptor, and \var{event} is a bitmaskwith bits set for the reported events for that descriptor--- \constant{POLLIN} for waiting input,\constant{POLLOUT} to indicate that the descriptor can be written to, andso forth.An empty list indicates that the call timed out and no filedescriptors had any events to report.If \var{timeout} is given, it specifies the length of time inmilliseconds which the system will wait for events before returning.If \var{timeout} is omitted, negative, or \constant{None}, the call willblock until there is an event for this poll object.\end{methoddesc}