\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()} functions
available in most operating systems.  Note that on Windows, it only
works for sockets; on other operating systems, it also works for other
file types (in particular, on \UNIX{}, it works on pipes).  It cannot
be used on regular files to determine whether a file has grown since
it was last read.

The module defines the following:

\begin{excdesc}{error}
The exception raised when an error occurs.  The accompanying value is
a pair containing the numeric error code from \cdata{errno} and the
corresponding 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, and
then polling them for I/O events; 
see section~\ref{poll-objects} below for the methods supported by 
polling 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 lists of `waitable
objects': either integers representing file descriptors or
objects with a parameterless method named \method{fileno()} returning
such an integer.  The three lists of waitable objects are for input,
output and `exceptional conditions', respectively.  Empty lists are
allowed, but acceptance of three empty lists 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 number
in seconds.  When the \var{timeout} argument is omitted the function
blocks until at least one file descriptor is ready.  A time-out value
of 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 reached
without a file descriptor becoming ready, three empty lists are
returned.

Amongst the acceptable object types in the lists are Python file
objects (e.g. \code{sys.stdin}, or objects returned by
\function{open()} or \function{os.popen()}), socket objects
returned 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 has
an appropriate \method{fileno()} method (that really returns a file
descriptor, not just a random integer).
\strong{Note:}\index{WinSock}  File objects on Windows are not
acceptable, but sockets are.  On Windows, the underlying
\cfunction{select()} function is provided by the WinSock library, and
does not handle file desciptors 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 only
requires listing the file descriptors of interest, while \cfunction{select()}
builds a bitmap, turns on bits for the fds of interest, and then
afterward 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 to
the \method{poll()} method will then check whether the file descriptor
has any pending I/O events.  \var{fd} can be either an integer, or an
object with a \method{fileno()} method that returns an integer.  File
objects implement
\method{fileno()}, so they can also be used as the argument.

\var{eventmask} is an optional bitmask describing the type of events you
want 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 value
used 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 an
error, and has the same effect as registering the descriptor exactly
once. 
 
\end{methoddesc}

\begin{methoddesc}{unregister}{fd}
Remove a file descriptor being tracked by a polling object.  Just like
the \method{register()} method, \var{fd} can be an integer or an
object with a \method{fileno()} method that returns an integer.

Attempting to remove a file descriptor that was never registered
causes a \exception{KeyError} exception to be raised.
\end{methoddesc}

\begin{methoddesc}{poll}{\optional{timeout}}
Polls the set of registered file descriptors, and returns a
possibly-empty list containing \code{(\var{fd}, \var{event})} 2-tuples
for the descriptors that have events or errors to report.
\var{fd} is the file descriptor, and \var{event} is a bitmask 
with 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, and
so forth.
An empty list indicates that the call timed out and no file
descriptors had any events to report.
If \var{timeout} is given, it specifies the length of time in
milliseconds which the system will wait for events before returning.
If \var{timeout} is omitted, negative, or \code{None}, the call will
block until there is an event for this poll object.
\end{methoddesc}