\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}{code}{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.
\end{methoddesc}