255 lines
11 KiB
TeX
255 lines
11 KiB
TeX
\section{\module{asynchat} ---
|
|
Asynchronous socket command/response handler}
|
|
|
|
\declaremodule{standard}{asynchat}
|
|
\modulesynopsis{Support for asynchronous command/response protocols.}
|
|
\moduleauthor{Sam Rushing}{rushing@nightmare.com}
|
|
\sectionauthor{Steve Holden}{sholden@holdenweb.com}
|
|
|
|
This module builds on the \refmodule{asyncore} infrastructure,
|
|
simplifying asynchronous clients and servers and making it easier to
|
|
handle protocols whose elements are terminated by arbitrary strings, or
|
|
are of variable length. \refmodule{asynchat} defines the abstract class
|
|
\class{async_chat} that you subclass, providing implementations of the
|
|
\method{collect_incoming_data()} and \method{found_terminator()}
|
|
methods. It uses the same asynchronous loop as \refmodule{asyncore}, and
|
|
the two types of channel, \class{asyncore.dispatcher} and
|
|
\class{asynchat.async_chat}, can freely be mixed in the channel map.
|
|
Typically an \class{asyncore.dispatcher} server channel generates new
|
|
\class{asynchat.async_chat} channel objects as it receives incoming
|
|
connection requests.
|
|
|
|
\begin{classdesc}{async_chat}{}
|
|
This class is an abstract subclass of \class{asyncore.dispatcher}. To make
|
|
practical use of the code you must subclass \class{async_chat}, providing
|
|
meaningful \method{collect_incoming_data()} and \method{found_terminator()}
|
|
methods. The \class{asyncore.dispatcher} methods can be
|
|
used, although not all make sense in a message/response context.
|
|
|
|
Like \class{asyncore.dispatcher}, \class{async_chat} defines a set of events
|
|
that are generated by an analysis of socket conditions after a
|
|
\cfunction{select()} call. Once the polling loop has been started the
|
|
\class{async_chat} object's methods are called by the event-processing
|
|
framework with no action on the part of the programmer.
|
|
|
|
Unlike \class{asyncore.dispatcher}, \class{async_chat} allows you to define
|
|
a first-in-first-out queue (fifo) of \emph{producers}. A producer need have
|
|
only one method, \method{more()}, which should return data to be transmitted
|
|
on the channel. The producer indicates exhaustion (\emph{i.e.} that it contains
|
|
no more data) by having its \method{more()} method return the empty string. At
|
|
this point the \class{async_chat} object removes the producer from the fifo
|
|
and starts using the next producer, if any. When the producer fifo is empty
|
|
the \method{handle_write()} method does nothing. You use the channel object's
|
|
\method{set_terminator()} method to describe how to recognize the end
|
|
of, or an important breakpoint in, an incoming transmission from the
|
|
remote endpoint.
|
|
|
|
To build a functioning \class{async_chat} subclass your
|
|
input methods \method{collect_incoming_data()} and
|
|
\method{found_terminator()} must handle the data that the channel receives
|
|
asynchronously. The methods are described below.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{close_when_done}{}
|
|
Pushes a \code{None} on to the producer fifo. When this producer is
|
|
popped off the fifo it causes the channel to be closed.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{collect_incoming_data}{data}
|
|
Called with \var{data} holding an arbitrary amount of received data.
|
|
The default method, which must be overridden, raises a \exception{NotImplementedError} exception.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{discard_buffers}{}
|
|
In emergencies this method will discard any data held in the input and/or
|
|
output buffers and the producer fifo.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{found_terminator}{}
|
|
Called when the incoming data stream matches the termination condition
|
|
set by \method{set_terminator}. The default method, which must be overridden,
|
|
raises a \exception{NotImplementedError} exception. The buffered input data should
|
|
be available via an instance attribute.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{get_terminator}{}
|
|
Returns the current terminator for the channel.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_close}{}
|
|
Called when the channel is closed. The default method silently closes
|
|
the channel's socket.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_read}{}
|
|
Called when a read event fires on the channel's socket in the
|
|
asynchronous loop. The default method checks for the termination
|
|
condition established by \method{set_terminator()}, which can be either
|
|
the appearance of a particular string in the input stream or the receipt
|
|
of a particular number of characters. When the terminator is found,
|
|
\method{handle_read} calls the \method{found_terminator()} method after
|
|
calling \method{collect_incoming_data()} with any data preceding the
|
|
terminating condition.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_write}{}
|
|
Called when the application may write data to the channel.
|
|
The default method calls the \method{initiate_send()} method, which in turn
|
|
will call \method{refill_buffer()} to collect data from the producer
|
|
fifo associated with the channel.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{push}{data}
|
|
Creates a \class{simple_producer} object (\emph{see below}) containing the data and
|
|
pushes it on to the channel's \code{producer_fifo} to ensure its
|
|
transmission. This is all you need to do to have the channel write
|
|
the data out to the network, although it is possible to use your
|
|
own producers in more complex schemes to implement encryption and
|
|
chunking, for example.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{push_with_producer}{producer}
|
|
Takes a producer object and adds it to the producer fifo associated with
|
|
the channel. When all currently-pushed producers have been exhausted
|
|
the channel will consume this producer's data by calling its
|
|
\method{more()} method and send the data to the remote endpoint.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{readable}{}
|
|
Should return \code{True} for the channel to be included in the set of
|
|
channels tested by the \cfunction{select()} loop for readability.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{refill_buffer}{}
|
|
Refills the output buffer by calling the \method{more()} method of the
|
|
producer at the head of the fifo. If it is exhausted then the
|
|
producer is popped off the fifo and the next producer is activated.
|
|
If the current producer is, or becomes, \code{None} then the channel
|
|
is closed.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{set_terminator}{term}
|
|
Sets the terminating condition to be recognised on the channel. \code{term}
|
|
may be any of three types of value, corresponding to three different ways
|
|
to handle incoming protocol data.
|
|
|
|
\begin{tableii}{l|l}{}{term}{Description}
|
|
\lineii{\emph{string}}{Will call \method{found_terminator()} when the
|
|
string is found in the input stream}
|
|
\lineii{\emph{integer}}{Will call \method{found_terminator()} when the
|
|
indicated number of characters have been received}
|
|
\lineii{\code{None}}{The channel continues to collect data forever}
|
|
\end{tableii}
|
|
|
|
Note that any data following the terminator will be available for reading by
|
|
the channel after \method{found_terminator()} is called.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{writable}{}
|
|
Should return \code{True} as long as items remain on the producer fifo,
|
|
or the channel is connected and the channel's output buffer is non-empty.
|
|
\end{methoddesc}
|
|
|
|
\subsection{asynchat - Auxiliary Classes and Functions}
|
|
|
|
\begin{classdesc}{simple_producer}{data\optional{, buffer_size=512}}
|
|
A \class{simple_producer} takes a chunk of data and an optional buffer size.
|
|
Repeated calls to its \method{more()} method yield successive chunks of the
|
|
data no larger than \var{buffer_size}.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{more}{}
|
|
Produces the next chunk of information from the producer, or returns the empty string.
|
|
\end{methoddesc}
|
|
|
|
\begin{classdesc}{fifo}{\optional{list=None}}
|
|
Each channel maintains a \class{fifo} holding data which has been pushed by the
|
|
application but not yet popped for writing to the channel.
|
|
A \class{fifo} is a list used to hold data and/or producers until they are required.
|
|
If the \var{list} argument is provided then it should contain producers or
|
|
data items to be written to the channel.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{is_empty}{}
|
|
Returns \code{True} iff the fifo is empty.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{first}{}
|
|
Returns the least-recently \method{push()}ed item from the fifo.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{push}{data}
|
|
Adds the given data (which may be a string or a producer object) to the
|
|
producer fifo.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{pop}{}
|
|
If the fifo is not empty, returns \code{True, first()}, deleting the popped
|
|
item. Returns \code{False, None} for an empty fifo.
|
|
\end{methoddesc}
|
|
|
|
The \module{asynchat} module also defines one utility function, which may be
|
|
of use in network and textual analysis operations.
|
|
|
|
\begin{funcdesc}{find_prefix_at_end}{haystack, needle}
|
|
Returns \code{True} if string \var{haystack} ends with any non-empty
|
|
prefix of string \var{needle}.
|
|
\end{funcdesc}
|
|
|
|
\subsection{asynchat Example \label{asynchat-example}}
|
|
|
|
The following partial example shows how HTTP requests can be read with
|
|
\class{async_chat}. A web server might create an \class{http_request_handler} object for
|
|
each incoming client connection. Notice that initially the
|
|
channel terminator is set to match the blank line at the end of the HTTP
|
|
headers, and a flag indicates that the headers are being read.
|
|
|
|
Once the headers have been read, if the request is of type POST
|
|
(indicating that further data are present in the input stream) then the
|
|
\code{Content-Length:} header is used to set a numeric terminator to
|
|
read the right amount of data from the channel.
|
|
|
|
The \method{handle_request()} method is called once all relevant input
|
|
has been marshalled, after setting the channel terminator to \code{None}
|
|
to ensure that any extraneous data sent by the web client are ignored.
|
|
|
|
\begin{verbatim}
|
|
class http_request_handler(asynchat.async_chat):
|
|
|
|
def __init__(self, conn, addr, sessions, log):
|
|
asynchat.async_chat.__init__(self, conn=conn)
|
|
self.addr = addr
|
|
self.sessions = sessions
|
|
self.ibuffer = []
|
|
self.obuffer = ""
|
|
self.set_terminator("\r\n\r\n")
|
|
self.reading_headers = True
|
|
self.handling = False
|
|
self.cgi_data = None
|
|
self.log = log
|
|
|
|
def collect_incoming_data(self, data):
|
|
"""Buffer the data"""
|
|
self.ibuffer.append(data)
|
|
|
|
def found_terminator(self):
|
|
if self.reading_headers:
|
|
self.reading_headers = False
|
|
self.parse_headers("".join(self.ibuffer))
|
|
self.ibuffer = []
|
|
if self.op.upper() == "POST":
|
|
clen = self.headers.getheader("content-length")
|
|
self.set_terminator(int(clen))
|
|
else:
|
|
self.handling = True
|
|
self.set_terminator(None)
|
|
self.handle_request()
|
|
elif not self.handling:
|
|
self.set_terminator(None) # browsers sometimes over-send
|
|
self.cgi_data = parse(self.headers, "".join(self.ibuffer))
|
|
self.handling = True
|
|
self.ibuffer = []
|
|
self.handle_request()
|
|
\end{verbatim}
|
|
|