--- rest25/library/asyncore.rst	2008-12-19 16:58:08.000000000 +0900
+++ rest262/library/asyncore.rst	2009-04-05 05:02:09.000000000 +0900
@@ -1,239 +1,250 @@
 
 :mod:`asyncore` --- Asynchronous socket handler
 ===============================================
 
 .. module:: asyncore
-   :synopsis: A base class for developing asynchronous socket  handling services.
+   :synopsis: A base class for developing asynchronous socket handling
+              services.
 .. moduleauthor:: Sam Rushing <rushing@nightmare.com>
 .. sectionauthor:: Christopher Petrilli <petrilli@amber.org>
 .. sectionauthor:: Steve Holden <sholden@holdenweb.com>
+.. heavily adapted from original documentation by Sam Rushing
 
 
 This module provides the basic infrastructure for writing asynchronous  socket
 service clients and servers.
 
-.. % Heavily adapted from original documentation by Sam Rushing.
-
 There are only two ways to have a program on a single processor do  "more than
 one thing at a time." Multi-threaded programming is the  simplest and most
-popular way to do it, but there is another very  different technique, that lets
+popular way to do it, but there is another very different technique, that lets
 you have nearly all the advantages of  multi-threading, without actually using
 multiple threads.  It's really  only practical if your program is largely I/O
-bound.  If your program  is processor bound, then pre-emptive scheduled threads
-are probably what  you really need. Network servers are rarely processor bound,
-however.
-
-If your operating system supports the :cfunc:`select` system call  in its I/O
-library (and nearly all do), then you can use it to juggle  multiple
-communication channels at once; doing other work while your  I/O is taking place
-in the "background."  Although this strategy can  seem strange and complex,
-especially at first, it is in many ways  easier to understand and control than
-multi-threaded programming.   The :mod:`asyncore` module solves many of the
-difficult problems for  you, making the task of building sophisticated high-
-performance  network servers and clients a snap. For "conversational"
-applications and protocols the companion  :mod:`asynchat` module is invaluable.
-
-The basic idea behind both modules is to create one or more network *channels*,
-instances of class :class:`asyncore.dispatcher` and
-:class:`asynchat.async_chat`. Creating the channels adds them to a global map,
-used by the :func:`loop` function if you do not provide it with your own *map*.
+bound.  If your program is processor bound, then pre-emptive scheduled threads
+are probably what you really need.  Network servers are rarely processor
+bound, however.
+
+If your operating system supports the :cfunc:`select` system call in its I/O
+library (and nearly all do), then you can use it to juggle multiple
+communication channels at once; doing other work while your I/O is taking
+place in the "background."  Although this strategy can seem strange and
+complex, especially at first, it is in many ways easier to understand and
+control than multi-threaded programming.  The :mod:`asyncore` module solves
+many of the difficult problems for you, making the task of building
+sophisticated high-performance network servers and clients a snap.  For
+"conversational" applications and protocols the companion :mod:`asynchat`
+module is invaluable.
+
+The basic idea behind both modules is to create one or more network
+*channels*, instances of class :class:`asyncore.dispatcher` and
+:class:`asynchat.async_chat`.  Creating the channels adds them to a global
+map, used by the :func:`loop` function if you do not provide it with your own
+*map*.
 
 Once the initial channel(s) is(are) created, calling the :func:`loop` function
-activates channel service, which continues until the last channel (including any
-that have been added to the map during asynchronous service) is closed.
+activates channel service, which continues until the last channel (including
+any that have been added to the map during asynchronous service) is closed.
 
 
 .. function:: loop([timeout[, use_poll[, map[,count]]]])
 
-   Enter a polling loop that terminates after count passes or all open channels
-   have been closed.  All arguments are optional.  The *(*count) parameter defaults
-   to None, resulting in the loop terminating only when all channels have been
-   closed.  The *timeout* argument sets the timeout parameter for the appropriate
-   :func:`select` or :func:`poll` call, measured in seconds; the default is 30
-   seconds. The *use_poll* parameter, if true, indicates that :func:`poll` should
-   be used in preference to :func:`select` (the default is ``False``).
-
-   The *map* parameter is a dictionary whose items are the channels to watch.  As
-   channels are closed they are deleted from their map.  If *map* is omitted, a
-   global map is used. Channels (instances of :class:`asyncore.dispatcher`,
-   :class:`asynchat.async_chat` and subclasses thereof) can freely be mixed in the
-   map.
+   Enter a polling loop that terminates after count passes or all open
+   channels have been closed.  All arguments are optional.  The *count*
+   parameter defaults to None, resulting in the loop terminating only when all
+   channels have been closed.  The *timeout* argument sets the timeout
+   parameter for the appropriate :func:`select` or :func:`poll` call, measured
+   in seconds; the default is 30 seconds.  The *use_poll* parameter, if true,
+   indicates that :func:`poll` should be used in preference to :func:`select`
+   (the default is ``False``).
+
+   The *map* parameter is a dictionary whose items are the channels to watch.
+   As channels are closed they are deleted from their map.  If *map* is
+   omitted, a global map is used. Channels (instances of
+   :class:`asyncore.dispatcher`, :class:`asynchat.async_chat` and subclasses
+   thereof) can freely be mixed in the map.
 
 
 .. class:: dispatcher()
 
    The :class:`dispatcher` class is a thin wrapper around a low-level socket
-   object. To make it more useful, it has a few methods for event-handling  which
-   are called from the asynchronous loop.   Otherwise, it can be treated as a
-   normal non-blocking socket object.
-
-   Two class attributes can be modified, to improve performance, or possibly even
-   to conserve memory.
-
-
-   .. data:: ac_in_buffer_size
-
-      The asynchronous input buffer size (default ``4096``).
-
-
-   .. data:: ac_out_buffer_size
-
-      The asynchronous output buffer size (default ``4096``).
-
-   The firing of low-level events at certain times or in certain connection states
-   tells the asynchronous loop that certain higher-level events have taken place.
-   For example, if we have asked for a socket to connect to another host, we know
-   that the connection has been made when the socket becomes writable for the first
-   time (at this point you know that you may write to it with the expectation of
-   success). The implied higher-level events are:
+   object. To make it more useful, it has a few methods for event-handling
+   which are called from the asynchronous loop.   Otherwise, it can be treated
+   as a normal non-blocking socket object.
+
+   The firing of low-level events at certain times or in certain connection
+   states tells the asynchronous loop that certain higher-level events have
+   taken place.  For example, if we have asked for a socket to connect to
+   another host, we know that the connection has been made when the socket
+   becomes writable for the first time (at this point you know that you may
+   write to it with the expectation of success).  The implied higher-level
+   events are:
 
    +----------------------+----------------------------------------+
    | Event                | Description                            |
    +======================+========================================+
    | ``handle_connect()`` | Implied by the first write event       |
    +----------------------+----------------------------------------+
    | ``handle_close()``   | Implied by a read event with no data   |
    |                      | available                              |
    +----------------------+----------------------------------------+
    | ``handle_accept()``  | Implied by a read event on a listening |
    |                      | socket                                 |
    +----------------------+----------------------------------------+
 
    During asynchronous processing, each mapped channel's :meth:`readable` and
    :meth:`writable` methods are used to determine whether the channel's socket
-   should be added to the list of channels :cfunc:`select`\ ed or :cfunc:`poll`\ ed
-   for read and write events.
+   should be added to the list of channels :cfunc:`select`\ ed or
+   :cfunc:`poll`\ ed for read and write events.
+
+   Thus, the set of channel events is larger than the basic socket events.  The
+   full set of methods that can be overridden in your subclass follows:
+
+
+   .. method:: handle_read()
 
-Thus, the set of channel events is larger than the basic socket events. The full
-set of methods that can be overridden in your subclass follows:
+      Called when the asynchronous loop detects that a :meth:`read` call on the
+      channel's socket will succeed.
 
 
-.. method:: dispatcher.handle_read()
+   .. method:: handle_write()
 
-   Called when the asynchronous loop detects that a :meth:`read` call on the
-   channel's socket will succeed.
+      Called when the asynchronous loop detects that a writable socket can be
+      written.  Often this method will implement the necessary buffering for
+      performance.  For example::
 
+         def handle_write(self):
+             sent = self.send(self.buffer)
+             self.buffer = self.buffer[sent:]
 
-.. method:: dispatcher.handle_write()
 
-   Called when the asynchronous loop detects that a writable socket can be written.
-   Often this method will implement the necessary buffering for  performance.  For
-   example::
+   .. method:: handle_expt()
 
-      def handle_write(self):
-          sent = self.send(self.buffer)
-          self.buffer = self.buffer[sent:]
+      Called when there is out of band (OOB) data for a socket connection.  This
+      will almost never happen, as OOB is tenuously supported and rarely used.
 
 
-.. method:: dispatcher.handle_expt()
+   .. method:: handle_connect()
 
-   Called when there is out of band (OOB) data for a socket  connection.  This will
-   almost never happen, as OOB is  tenuously supported and rarely used.
+      Called when the active opener's socket actually makes a connection.  Might
+      send a "welcome" banner, or initiate a protocol negotiation with the
+      remote endpoint, for example.
 
 
-.. method:: dispatcher.handle_connect()
+   .. method:: handle_close()
 
-   Called when the active opener's socket actually makes a connection. Might send a
-   "welcome" banner, or initiate a protocol negotiation with the remote endpoint,
-   for example.
+      Called when the socket is closed.
 
 
-.. method:: dispatcher.handle_close()
+   .. method:: handle_error()
 
-   Called when the socket is closed.
+      Called when an exception is raised and not otherwise handled.  The default
+      version prints a condensed traceback.
 
 
-.. method:: dispatcher.handle_error()
+   .. method:: handle_accept()
 
-   Called when an exception is raised and not otherwise handled.  The default
-   version prints a condensed traceback.
+      Called on listening channels (passive openers) when a connection can be
+      established with a new remote endpoint that has issued a :meth:`connect`
+      call for the local endpoint.
 
 
-.. method:: dispatcher.handle_accept()
+   .. method:: readable()
 
-   Called on listening channels (passive openers) when a   connection can be
-   established with a new remote endpoint that has issued a :meth:`connect` call
-   for the local endpoint.
+      Called each time around the asynchronous loop to determine whether a
+      channel's socket should be added to the list on which read events can
+      occur.  The default method simply returns ``True``, indicating that by
+      default, all channels will be interested in read events.
 
 
-.. method:: dispatcher.readable()
+   .. method:: writable()
 
-   Called each time around the asynchronous loop to determine whether a channel's
-   socket should be added to the list on which read events can occur.  The default
-   method simply returns ``True``,  indicating that by default, all channels will
-   be interested in read events.
+      Called each time around the asynchronous loop to determine whether a
+      channel's socket should be added to the list on which write events can
+      occur.  The default method simply returns ``True``, indicating that by
+      default, all channels will be interested in write events.
 
 
-.. method:: dispatcher.writable()
+   In addition, each channel delegates or extends many of the socket methods.
+   Most of these are nearly identical to their socket partners.
 
-   Called each time around the asynchronous loop to determine whether a channel's
-   socket should be added to the list on which write events can occur.  The default
-   method simply returns ``True``,  indicating that by default, all channels will
-   be interested in write events.
 
-In addition, each channel delegates or extends many of the socket methods. Most
-of these are nearly identical to their socket partners.
+   .. method:: create_socket(family, type)
 
+      This is identical to the creation of a normal socket, and will use the
+      same options for creation.  Refer to the :mod:`socket` documentation for
+      information on creating sockets.
 
-.. method:: dispatcher.create_socket(family, type)
 
-   This is identical to the creation of a normal socket, and  will use the same
-   options for creation.  Refer to the :mod:`socket` documentation for information
-   on creating sockets.
+   .. method:: connect(address)
 
+      As with the normal socket object, *address* is a tuple with the first
+      element the host to connect to, and the second the port number.
 
-.. method:: dispatcher.connect(address)
 
-   As with the normal socket object, *address* is a  tuple with the first element
-   the host to connect to, and the  second the port number.
+   .. method:: send(data)
 
+      Send *data* to the remote end-point of the socket.
 
-.. method:: dispatcher.send(data)
 
-   Send *data* to the remote end-point of the socket.
+   .. method:: recv(buffer_size)
 
+      Read at most *buffer_size* bytes from the socket's remote end-point.  An
+      empty string implies that the channel has been closed from the other end.
 
-.. method:: dispatcher.recv(buffer_size)
 
-   Read at most *buffer_size* bytes from the socket's remote end-point. An empty
-   string implies that the channel has been closed from the other end.
+   .. method:: listen(backlog)
 
+      Listen for connections made to the socket.  The *backlog* argument
+      specifies the maximum number of queued connections and should be at least
+      1; the maximum value is system-dependent (usually 5).
 
-.. method:: dispatcher.listen(backlog)
 
-   Listen for connections made to the socket.  The *backlog* argument specifies the
-   maximum number of queued connections and should be at least 1; the maximum value
-   is system-dependent (usually 5).
+   .. method:: bind(address)
 
+      Bind the socket to *address*.  The socket must not already be bound.  (The
+      format of *address* depends on the address family --- see above.)  To mark
+      the socket as re-usable (setting the :const:`SO_REUSEADDR` option), call
+      the :class:`dispatcher` object's :meth:`set_reuse_addr` method.
 
-.. method:: dispatcher.bind(address)
 
-   Bind the socket to *address*.  The socket must not already be bound.  (The
-   format of *address* depends on the address family --- see above.)
+   .. method:: accept()
 
+      Accept a connection.  The socket must be bound to an address and listening
+      for connections.  The return value is a pair ``(conn, address)`` where
+      *conn* is a *new* socket object usable to send and receive data on the
+      connection, and *address* is the address bound to the socket on the other
+      end of the connection.
 
-.. method:: dispatcher.accept()
 
-   Accept a connection.  The socket must be bound to an address and listening for
-   connections.  The return value is a pair ``(conn, address)`` where *conn* is a
-   *new* socket object usable to send and receive data on the connection, and
-   *address* is the address bound to the socket on the other end of the connection.
+   .. method:: close()
 
+      Close the socket.  All future operations on the socket object will fail.
+      The remote end-point will receive no more data (after queued data is
+      flushed).  Sockets are automatically closed when they are
+      garbage-collected.
 
-.. method:: dispatcher.close()
+.. class:: file_dispatcher()
 
-   Close the socket.  All future operations on the socket object will fail.  The
-   remote end-point will receive no more data (after queued data is flushed).
-   Sockets are automatically closed when they are garbage-collected.
+   A file_dispatcher takes a file descriptor or file object along with an
+   optional map argument and wraps it for use with the :cfunc:`poll` or
+   :cfunc:`loop` functions.  If provided a file object or anything with a
+   :cfunc:`fileno` method, that method will be called and passed to the
+   :class:`file_wrapper` constructor.  Availability: UNIX.
+
+.. class:: file_wrapper()
+
+   A file_wrapper takes an integer file descriptor and calls :func:`os.dup` to
+   duplicate the handle so that the original handle may be closed independently
+   of the file_wrapper.  This class implements sufficient methods to emulate a
+   socket for use by the :class:`file_dispatcher` class.  Availability: UNIX.
 
 
 .. _asyncore-example:
 
 asyncore Example basic HTTP client
 ----------------------------------
 
 Here is a very basic HTTP client that uses the :class:`dispatcher` class to
 implement its socket handling::
 
    import asyncore, socket
 
@@ -255,13 +266,12 @@
            print self.recv(8192)
 
        def writable(self):
            return (len(self.buffer) > 0)
 
        def handle_write(self):
            sent = self.send(self.buffer)
            self.buffer = self.buffer[sent:]
 
    c = http_client('www.python.org', '/')
 
    asyncore.loop()
-
