diff options
Diffstat (limited to 'Doc/lib/libselect.tex')
-rw-r--r-- | Doc/lib/libselect.tex | 132 |
1 files changed, 0 insertions, 132 deletions
diff --git a/Doc/lib/libselect.tex b/Doc/lib/libselect.tex deleted file mode 100644 index 69583d4..0000000 --- a/Doc/lib/libselect.tex +++ /dev/null @@ -1,132 +0,0 @@ -\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 sequences of `waitable -objects': either integers representing file descriptors or -objects with a parameterless method named \method{fileno()} returning -such an integer. The three sequences of waitable objects are for input, -output and `exceptional conditions', respectively. Empty sequences are -allowed, 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 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. - -Among the acceptable object types in the sequences 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). -\note{File objects on Windows are not acceptable, but sockets -are.\index{WinSock} On Windows, the underlying \cfunction{select()} -function is provided by the WinSock library, and does not handle file -descriptors 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}[poll]{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}[poll]{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]{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 \constant{None}, the call will -block until there is an event for this poll object. -\end{methoddesc} |