Move the 3k reST doc tree in place.

1 files changed, 141 insertions, 0 deletions

diff --git a/Doc/library/select.rst b/Doc/library/select.rst
new file mode 100644
index 0000000..f68a0da
--- /dev/null
+++ b/Doc/library/select.rst
@@ -0,0 +1,141 @@
+
+:mod:`select` --- Waiting for I/O completion
+============================================
+
+.. module:: select
+   :synopsis: Wait for I/O completion on multiple streams.
+
+
+This module provides access to the :cfunc:`select` and :cfunc:`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:
+
+
+.. exception:: 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 :cfunc:`perror`.
+
+
+.. function:: 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.
+
+
+.. function:: select(iwtd, owtd, ewtd[, timeout])
+
+   This is a straightforward interface to the Unix :cfunc:`select` system call.
+   The first three arguments are sequences of 'waitable objects': either
+   integers representing file descriptors or objects with a parameterless method
+   named :meth:`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 *timeout* argument specifies a time-out as a floating
+   point number in seconds.  When the *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.
+
+   .. index::
+      single: socket() (in module socket)
+      single: popen() (in module os)
+
+   Among the acceptable object types in the sequences are Python file objects (e.g.
+   ``sys.stdin``, or objects returned by :func:`open` or :func:`os.popen`), socket
+   objects returned by :func:`socket.socket`.  You may also define a :dfn:`wrapper`
+   class yourself, as long as it has an appropriate :meth:`fileno` method (that
+   really returns a file descriptor, not just a random integer).
+
+   .. % 
+
+   .. note::
+
+      .. index:: single: WinSock
+
+      File objects on Windows are not acceptable, but sockets are.  On Windows, the
+      underlying :cfunc:`select` function is provided by the WinSock library, and does
+      not handle file descriptors that don't originate from WinSock.
+
+
+.. _poll-objects:
+
+Polling Objects
+---------------
+
+The :cfunc:`poll` system call, supported on most Unix systems, provides better
+scalability for network servers that service many, many clients at the same
+time. :cfunc:`poll` scales better because the system call only requires listing
+the file descriptors of interest, while :cfunc:`select` builds a bitmap, turns
+on bits for the fds of interest, and then afterward the whole bitmap has to be
+linearly scanned again. :cfunc:`select` is O(highest file descriptor), while
+:cfunc:`poll` is O(number of file descriptors).
+
+
+.. method:: poll.register(fd[, eventmask])
+
+   Register a file descriptor with the polling object.  Future calls to the
+   :meth:`poll` method will then check whether the file descriptor has any pending
+   I/O events.  *fd* can be either an integer, or an object with a :meth:`fileno`
+   method that returns an integer.  File objects implement :meth:`fileno`, so they
+   can also be used as the argument.
+
+   *eventmask* is an optional bitmask describing the type of events you want to
+   check for, and can be a combination of the constants :const:`POLLIN`,
+   :const:`POLLPRI`, and :const:`POLLOUT`, described in the table below.  If not
+   specified, the default value used will check for all 3 types of events.
+
+   +-------------------+------------------------------------------+
+   | Constant          | Meaning                                  |
+   +===================+==========================================+
+   | :const:`POLLIN`   | There is data to read                    |
+   +-------------------+------------------------------------------+
+   | :const:`POLLPRI`  | There is urgent data to read             |
+   +-------------------+------------------------------------------+
+   | :const:`POLLOUT`  | Ready for output: writing will not block |
+   +-------------------+------------------------------------------+
+   | :const:`POLLERR`  | Error condition of some sort             |
+   +-------------------+------------------------------------------+
+   | :const:`POLLHUP`  | Hung up                                  |
+   +-------------------+------------------------------------------+
+   | :const:`POLLNVAL` | Invalid request: descriptor not open     |
+   +-------------------+------------------------------------------+
+
+   Registering a file descriptor that's already registered is not an error, and has
+   the same effect as registering the descriptor exactly once.
+
+
+.. method:: poll.unregister(fd)
+
+   Remove a file descriptor being tracked by a polling object.  Just like the
+   :meth:`register` method, *fd* can be an integer or an object with a
+   :meth:`fileno` method that returns an integer.
+
+   Attempting to remove a file descriptor that was never registered causes a
+   :exc:`KeyError` exception to be raised.
+
+
+.. method:: poll.poll([timeout])
+
+   Polls the set of registered file descriptors, and returns a possibly-empty list
+   containing ``(fd, event)`` 2-tuples for the descriptors that have events or
+   errors to report. *fd* is the file descriptor, and *event* is a bitmask with
+   bits set for the reported events for that descriptor --- :const:`POLLIN` for
+   waiting input, :const:`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 *timeout* is given, it specifies the
+   length of time in milliseconds which the system will wait for events before
+   returning. If *timeout* is omitted, negative, or :const:`None`, the call will
+   block until there is an event for this poll object.
+