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 function \cfunction{select()}
   9 available in most operating systems.  Note that on Windows, it only
  10 works for sockets; on other operating systems, it also works for other
  11 file types (in particular, on \UNIX{}, it works on pipes).  It cannot
  12 be used or regular files to determine whether a file has grown since
  13 it was last read.
  14
  15 The module defines the following:
  16
  17 \begin{excdesc}{error}
  18 The exception raised when an error occurs.  The accompanying value is
  19 a pair containing the numeric error code from \cdata{errno} and the
  20 corresponding string, as would be printed by the \C{} function
  21 \cfunction{perror()}.
  22 \end{excdesc}
  23
  24 \begin{funcdesc}{select}{iwtd, owtd, ewtd\optional{, timeout}}
  25 This is a straightforward interface to the \UNIX{} \cfunction{select()}
  26 system call.  The first three arguments are lists of `waitable
  27 objects': either integers representing \UNIX{} file descriptors or
  28 objects with a parameterless method named \method{fileno()} returning
  29 such an integer.  The three lists of waitable objects are for input,
  30 output and `exceptional conditions', respectively.  Empty lists are
  31 allowed.  The optional \var{timeout} argument specifies a time-out as a
  32 floating point number in seconds.  When the \var{timeout} argument
  33 is omitted the function blocks until at least one file descriptor is
  34 ready.  A time-out value of zero specifies a poll and never blocks.
  35
  36 The return value is a triple of lists of objects that are ready:
  37 subsets of the first three arguments.  When the time-out is reached
  38 without a file descriptor becoming ready, three empty lists are
  39 returned.
  40
  41 Amongst the acceptable object types in the lists are Python file
  42 objects (e.g. \code{sys.stdin}, or objects returned by
  43 \function{open()} or \function{os.popen()}), socket objects
  44 returned by \function{socket.socket()},%
  45 \withsubitem{(in module socket)}{\ttindex{socket()}}
  46 \withsubitem{(in module os)}{\ttindex{popen()}}
  47 and the module \module{stdwin}\refbimodindex{stdwin} which happens to
  48 define a function
  49 \function{fileno()}\withsubitem{(in module stdwin)}{\ttindex{fileno()}}
  50 for just this purpose.  You may
  51 also define a \dfn{wrapper} class yourself, as long as it has an
  52 appropriate \method{fileno()} method (that really returns a \UNIX{}
  53 file descriptor, not just a random integer).
  54 \end{funcdesc}