1998-08-10 19:42:37 +00:00
|
|
|
\section{\module{select} ---
|
1999-02-20 00:14:17 +00:00
|
|
|
Waiting for I/O completion}
|
1998-07-23 17:59:49 +00:00
|
|
|
|
1999-02-20 00:14:17 +00:00
|
|
|
\declaremodule{builtin}{select}
|
1998-07-23 17:59:49 +00:00
|
|
|
\modulesynopsis{Wait for I/O completion on multiple streams.}
|
|
|
|
|
1994-01-02 01:22:07 +00:00
|
|
|
|
2000-08-25 01:21:28 +00:00
|
|
|
This module provides access to the \cfunction{select()}
|
|
|
|
and \cfunction{poll()} functions
|
1998-09-28 14:28:38 +00:00
|
|
|
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
|
2000-04-03 20:13:55 +00:00
|
|
|
be used on regular files to determine whether a file has grown since
|
1998-09-28 14:28:38 +00:00
|
|
|
it was last read.
|
|
|
|
|
|
|
|
The module defines the following:
|
1994-01-02 01:22:07 +00:00
|
|
|
|
|
|
|
\begin{excdesc}{error}
|
|
|
|
The exception raised when an error occurs. The accompanying value is
|
1998-04-02 18:44:38 +00:00
|
|
|
a pair containing the numeric error code from \cdata{errno} and the
|
|
|
|
corresponding string, as would be printed by the \C{} function
|
|
|
|
\cfunction{perror()}.
|
1994-01-02 01:22:07 +00:00
|
|
|
\end{excdesc}
|
|
|
|
|
2000-08-25 01:21:28 +00:00
|
|
|
\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}
|
|
|
|
|
1998-03-17 06:33:25 +00:00
|
|
|
\begin{funcdesc}{select}{iwtd, owtd, ewtd\optional{, timeout}}
|
1998-04-02 18:44:38 +00:00
|
|
|
This is a straightforward interface to the \UNIX{} \cfunction{select()}
|
1994-01-02 01:22:07 +00:00
|
|
|
system call. The first three arguments are lists of `waitable
|
2000-12-11 15:50:07 +00:00
|
|
|
objects': either integers representing file descriptors or
|
1998-04-02 18:44:38 +00:00
|
|
|
objects with a parameterless method named \method{fileno()} returning
|
1994-01-02 01:22:07 +00:00
|
|
|
such an integer. The three lists of waitable objects are for input,
|
|
|
|
output and `exceptional conditions', respectively. Empty lists are
|
2000-12-11 15:50:07 +00:00
|
|
|
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.
|
1994-01-02 01:22:07 +00:00
|
|
|
|
|
|
|
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
|
1998-04-02 18:44:38 +00:00
|
|
|
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()}}
|
2000-12-11 15:50:07 +00:00
|
|
|
\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.
|
1994-01-02 01:22:07 +00:00
|
|
|
\end{funcdesc}
|
2000-08-25 01:21:28 +00:00
|
|
|
|
|
|
|
\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.
|
|
|
|
|
2001-07-11 18:48:39 +00:00
|
|
|
\begin{tableii}{l|l}{constant}{Constant}{Meaning}
|
2000-08-25 01:21:28 +00:00
|
|
|
\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.
|
2001-07-11 18:48:39 +00:00
|
|
|
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.
|
2000-08-25 01:21:28 +00:00
|
|
|
\end{methoddesc}
|
|
|
|
|
|
|
|
|