Doc/lib/libselect.tex

   1 \section{\module{select} ---
   2          Waiting for I/O completion}
   3
   4 \declaremodule{builtin}{select}
   5 \modulesynopsis{Wait for I/O completion on multiple streams.}
   6
   7
   8 This module provides access to the \cfunction{select()}
   9 and \cfunction{poll()} functions
  10 available in most operating systems.  Note that on Windows, it only
  11 works for sockets; on other operating systems, it also works for other
  12 file types (in particular, on \UNIX{}, it works on pipes).  It cannot
  13 be used on regular files to determine whether a file has grown since
  14 it was last read.
  15
  16 The module defines the following:
  17
  18 \begin{excdesc}{error}
  19 The exception raised when an error occurs.  The accompanying value is
  20 a pair containing the numeric error code from \cdata{errno} and the
  21 corresponding string, as would be printed by the \C{} function
  22 \cfunction{perror()}.
  23 \end{excdesc}
  24
  25 \begin{funcdesc}{poll}{}
  26 (Not supported by all operating systems.)  Returns a polling object,
  27 which supports registering and unregistering file descriptors, and
  28 then polling them for I/O events;
  29 see section~\ref{poll-objects} below for the methods supported by
  30 polling objects.
  31 \end{funcdesc}
  32
  33 \begin{funcdesc}{select}{iwtd, owtd, ewtd\optional{, timeout}}
  34 This is a straightforward interface to the \UNIX{} \cfunction{select()}
  35 system call.  The first three arguments are lists of `waitable
  36 objects': either integers representing file descriptors or
  37 objects with a parameterless method named \method{fileno()} returning
  38 such an integer.  The three lists of waitable objects are for input,
  39 output and `exceptional conditions', respectively.  Empty lists are
  40 allowed, but acceptance of three empty lists is platform-dependent.
  41 (It is known to work on \UNIX{} but not on Windows.)  The optional
  42 \var{timeout} argument specifies a time-out as a floating point number
  43 in seconds.  When the \var{timeout} argument is omitted the function
  44 blocks until at least one file descriptor is ready.  A time-out value
  45 of zero specifies a poll and never blocks.
  46
  47 The return value is a triple of lists of objects that are ready:
  48 subsets of the first three arguments.  When the time-out is reached
  49 without a file descriptor becoming ready, three empty lists are
  50 returned.
  51
  52 Amongst the acceptable object types in the lists are Python file
  53 objects (e.g. \code{sys.stdin}, or objects returned by
  54 \function{open()} or \function{os.popen()}), socket objects
  55 returned by \function{socket.socket()},%
  56 \withsubitem{(in module socket)}{\ttindex{socket()}}
  57 \withsubitem{(in module os)}{\ttindex{popen()}}.
  58 You may also define a \dfn{wrapper} class yourself, as long as it has
  59 an appropriate \method{fileno()} method (that really returns a file
  60 descriptor, not just a random integer).
  61 \strong{Note:}\index{WinSock}  File objects on Windows are not
  62 acceptable, but sockets are.  On Windows, the underlying
  63 \cfunction{select()} function is provided by the WinSock library, and
  64 does not handle file desciptors that don't originate from WinSock.
  65 \end{funcdesc}
  66
  67 \subsection{Polling Objects
  68             \label{poll-objects}}
  69
  70 The \cfunction{poll()} system call, supported on most Unix systems,
  71 provides better scalability for network servers that service many,
  72 many clients at the same time.
  73 \cfunction{poll()} scales better because the system call only
  74 requires listing the file descriptors of interest, while \cfunction{select()}
  75 builds a bitmap, turns on bits for the fds of interest, and then
  76 afterward the whole bitmap has to be linearly scanned again.
  77 \cfunction{select()} is O(highest file descriptor), while
  78 \cfunction{poll()} is O(number of file descriptors).
  79
  80 \begin{methoddesc}{register}{fd\optional{, eventmask}}
  81 Register a file descriptor with the polling object.  Future calls to
  82 the \method{poll()} method will then check whether the file descriptor
  83 has any pending I/O events.  \var{fd} can be either an integer, or an
  84 object with a \method{fileno()} method that returns an integer.  File
  85 objects implement
  86 \method{fileno()}, so they can also be used as the argument.
  87
  88 \var{eventmask} is an optional bitmask describing the type of events you
  89 want to check for, and can be a combination of the constants
  90 \constant{POLLIN}, \constant{POLLPRI}, and \constant{POLLOUT},
  91 described in the table below.  If not specified, the default value
  92 used will check for all 3 types of events.
  93
  94 \begin{tableii}{l|l}{code}{Constant}{Meaning}
  95   \lineii{POLLIN}{There is data to read}
  96   \lineii{POLLPRI}{There is urgent data to read}
  97   \lineii{POLLOUT}{Ready for output: writing will not block}
  98   \lineii{POLLERR}{Error condition of some sort}
  99   \lineii{POLLHUP}{Hung up}
 100   \lineii{POLLNVAL}{Invalid request: descriptor not open}
 101 \end{tableii}
 102
 103 Registering a file descriptor that's already registered is not an
 104 error, and has the same effect as registering the descriptor exactly
 105 once.
 106
 107 \end{methoddesc}
 108
 109 \begin{methoddesc}{unregister}{fd}
 110 Remove a file descriptor being tracked by a polling object.  Just like
 111 the \method{register()} method, \var{fd} can be an integer or an
 112 object with a \method{fileno()} method that returns an integer.
 113
 114 Attempting to remove a file descriptor that was never registered
 115 causes a \exception{KeyError} exception to be raised.
 116 \end{methoddesc}
 117
 118 \begin{methoddesc}{poll}{\optional{timeout}}
 119 Polls the set of registered file descriptors, and returns a
 120 possibly-empty list containing \code{(\var{fd}, \var{event})} 2-tuples
 121 for the descriptors that have events or errors to report.
 122 \var{fd} is the file descriptor, and \var{event} is a bitmask
 123 with bits set for the reported events for that descriptor
 124 --- \constant{POLLIN} for waiting input,
 125 \constant{POLLOUT} to indicate that the descriptor can be written to, and
 126 so forth.
 127 An empty list indicates that the call timed out and no file
 128 descriptors had any events to report.
 129 \end{methoddesc}
 130
 131