Doc/library/select.rst

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