Revise asyncore documentation and document asynchat for the first time.

1 files changed, 91 insertions, 55 deletions

diff --git a/Doc/lib/libasyncore.tex b/Doc/lib/libasyncore.tex
index a85998e..be19295 100644
--- a/Doc/lib/libasyncore.tex
+++ b/Doc/lib/libasyncore.tex
@@ -6,6 +6,7 @@
                 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 
@@ -26,35 +27,21 @@ 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 module documented here solves many of the difficult problems for 
+The \module{asyncore} module solves many of the difficult problems for 
 you, making the task of building sophisticated high-performance 
-network servers and clients a snap.
+network servers and clients a snap. For ``conversational'' applications
+and protocols the companion  \refmodule{asynchat} module is invaluable.
 
-\begin{classdesc}{dispatcher}{}
-  The first class we will introduce is the \class{dispatcher} class. 
-  This is a thin wrapper around a low-level socket object.  To make 
-  it more useful, it has a few methods for event-handling on it.  
-  Otherwise, it can be treated as a normal non-blocking socket object.
+The basic idea behind both modules is to create one or more network
+\emph{channels}, instances of class \class{asyncore.dispatcher} and
+\class{asynchat.async_chat}. Creating the channels adds them to a global
+map, used by the \function{loop()} function if you do not provide it
+with your own \var{map}.
 
-  The direct interface between the select loop and the socket object
-  are the \method{handle_read_event()} and 
-  \method{handle_write_event()} methods. These are called whenever an 
-  object `fires' that event.
-
-  The firing of these low-level events can tell us whether certain 
-  higher-level events have taken place, depending on the timing and 
-  the state of the connection.  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 fires a write event (at this point you 
-  know that you may write to it with the expectation of success).  
-  The implied higher-level events are:
-
-  \begin{tableii}{l|l}{code}{Event}{Description}
-    \lineii{handle_connect()}{Implied by a write event}
-    \lineii{handle_close()}{Implied by a read event with no data available}
-    \lineii{handle_accept()}{Implied by a read event on a listening socket}
-  \end{tableii}
-\end{classdesc}
+Once the initial channel(s) is(are) created, calling the \function{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.
 
 \begin{funcdesc}{loop}{\optional{timeout\optional{, use_poll\optional{,
                        map}}}}
@@ -64,21 +51,67 @@ network servers and clients a snap.
   \function{select()} or \function{poll()} call, measured in seconds;
   the default is 30 seconds.  The \var{use_poll} parameter, if true,
   indicates that \function{poll()} should be used in preference to
-  \function{select()} (the default is false).  The \var{map} parameter
-  is a dictionary that gives a list of channels to watch.  As channels
+  \function{select()} (the default is \code{False}).  The \var{map} parameter
+  is a dictionary whose items are the channels to watch.  As channels
   are closed they are deleted from their map.  If \var{map} is
-  omitted, a global map is used.
+  omitted, a global map is used (this map is updated by the default
+  class \method{__init__()}
+  -- make sure you extend, rather than override, \method{__init__()}
+  if you want to retain this behavior).
+
+  Channels (instances of \class{asyncore.despatcher}, \class{asynchat.async_chat}
+  and subclasses thereof) can freely be mixed in the map.
 \end{funcdesc}
 
-This set of user-level events is larger than the basics.  The 
-full set of methods that can be overridden in your subclass are:
+\begin{classdesc}{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.
+
+  \begin{datadesc}{ac_in_buffer_size}
+  The asynchronous input buffer size (default \code{4096}).
+  \end{datadesc}
+
+  \begin{datadesc}{ac_out_buffer_size}
+  The asynchronous output buffer size (default \code{4096}).
+  \end{datadesc}
+
+  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:
+
+  \begin{tableii}{l|l}{code}{Event}{Description}
+    \lineii{handle_connect()}{Implied by the first write event}
+    \lineii{handle_close()}{Implied by a read event with no data available}
+    \lineii{handle_accept()}{Implied by a read event on a listening socket}
+  \end{tableii}
+
+  During asynchronous processing, each mapped channel's \method{readable()}
+  and \method{writable()} methods are used to determine whether the channel's
+  socket should be added to the list of channels \cfunction{select()}ed or
+  \cfunction{poll()}ed for read and write events.
+
+\end{classdesc}
+
+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:
 
 \begin{methoddesc}{handle_read}{}
-  Called when there is new data to be read from a socket.
+  Called when the asynchronous loop detects that a \method{read()}
+  call on the channel's socket will succeed.
 \end{methoddesc}
 
 \begin{methoddesc}{handle_write}{}
-  Called when there is an attempt to write data to the object.  
+  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:
 
@@ -96,9 +129,9 @@ def handle_write(self):
 \end{methoddesc}
 
 \begin{methoddesc}{handle_connect}{}
-  Called when the socket actually makes a connection.  This 
-  might be used to send a ``welcome'' banner, or something 
-  similar.
+  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.
 \end{methoddesc}
 
 \begin{methoddesc}{handle_close}{}
@@ -111,28 +144,29 @@ def handle_write(self):
 \end{methoddesc}
 
 \begin{methoddesc}{handle_accept}{}
-  Called on listening sockets when they actually accept a new 
-  connection.
+  Called on listening channels (passive openers) when a  
+  connection can be established with a new remote endpoint that
+  has issued a \method{connect()} call for the local endpoint.
 \end{methoddesc}
 
 \begin{methoddesc}{readable}{}
-  Each time through the \method{select()} loop, the set of sockets 
-  is scanned, and this method is called to see if there is any 
-  interest in reading.  The default method simply returns \code{True}, 
-  indicating that by default, all channels will be interested.
+  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 \code{True}, 
+  indicating that by default, all channels will be interested in
+  read events.
 \end{methoddesc}
 
 \begin{methoddesc}{writable}{}
-  Each time through the \method{select()} loop, the set of sockets 
-  is scanned, and this method is called to see if there is any 
-  interest in writing.  The default method simply returns \code{True}, 
-  indicating that by default, all channels will be interested.
+  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 \code{True}, 
+  indicating that by default, all channels will be interested in
+  write events.
 \end{methoddesc}
 
-In addition, there are the basic methods needed to construct and
-manipulate ``channels,'' which are what we will call the socket
-connections in this context. Note that most of these are nearly 
-identical to their socket partners.
+In addition, each channel delegates or extends many of the socket methods.
+Most of these are nearly identical to their socket partners.
 
 \begin{methoddesc}{create_socket}{family, type}
   This is identical to the creation of a normal socket, and 
@@ -144,15 +178,17 @@ identical to their socket partners.
 \begin{methoddesc}{connect}{address}
   As with the normal socket object, \var{address} is a 
   tuple with the first element the host to connect to, and the 
-  second the port.
+  second the port number.
 \end{methoddesc}
 
 \begin{methoddesc}{send}{data}
-  Send \var{data} out the socket.
+  Send \var{data} to the remote end-point of the socket.
 \end{methoddesc}
 
 \begin{methoddesc}{recv}{buffer_size}
-  Read at most \var{buffer_size} bytes from the socket.
+  Read at most \var{buffer_size} bytes from the socket's remote end-point.
+  An empty string implies that the channel has been closed from the other
+  end.
 \end{methoddesc}
 
 \begin{methoddesc}{listen}{backlog}
@@ -179,13 +215,13 @@ identical to their socket partners.
 
 \begin{methoddesc}{close}{}
   Close the socket.  All future operations on the socket object
-  will fail.  The remote end will receive no more data (after
+  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.
 \end{methoddesc}
 
 
-\subsection{Example basic HTTP client \label{asyncore-example}}
+\subsection{asyncore Example basic HTTP client \label{asyncore-example}}
 
 As a basic example, below is a very basic HTTP client that uses the 
 \class{dispatcher} class to implement its socket handling: