259 lines
10 KiB
TeX
259 lines
10 KiB
TeX
\section{\module{asyncore} ---
|
|
Asynchronous socket handler}
|
|
|
|
\declaremodule{builtin}{asyncore}
|
|
\modulesynopsis{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.
|
|
|
|
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 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 \cfunction{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 \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. For ``conversational'' applications
|
|
and protocols the companion \refmodule{asynchat} module is invaluable.
|
|
|
|
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}.
|
|
|
|
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\optional{,count}}}}}
|
|
Enter a polling loop that terminates after count passes or all open
|
|
channels have been closed. All arguments are optional. The \var(count)
|
|
parameter defaults to None, resulting in the loop terminating only
|
|
when all channels have been closed. The \var{timeout} argument sets the
|
|
timeout parameter for the appropriate \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
|
|
\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.
|
|
Channels (instances of \class{asyncore.dispatcher}, \class{asynchat.async_chat}
|
|
and subclasses thereof) can freely be mixed in the map.
|
|
\end{funcdesc}
|
|
|
|
\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 the asynchronous loop detects that a \method{read()}
|
|
call on the channel's socket will succeed.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{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:
|
|
|
|
\begin{verbatim}
|
|
def handle_write(self):
|
|
sent = self.send(self.buffer)
|
|
self.buffer = self.buffer[sent:]
|
|
\end{verbatim}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_expt}{}
|
|
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.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_connect}{}
|
|
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}{}
|
|
Called when the socket is closed.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_error}{}
|
|
Called when an exception is raised and not otherwise handled. The default
|
|
version prints a condensed traceback.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_accept}{}
|
|
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}{}
|
|
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}{}
|
|
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, 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
|
|
will use the same options for creation. Refer to the
|
|
\refmodule{socket} documentation for information on creating
|
|
sockets.
|
|
\end{methoddesc}
|
|
|
|
\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 number.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{send}{data}
|
|
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's remote end-point.
|
|
An empty string implies that the channel has been closed from the other
|
|
end.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{listen}{backlog}
|
|
Listen for connections made to the socket. The \var{backlog}
|
|
argument specifies the maximum number of queued connections
|
|
and should be at least 1; the maximum value is
|
|
system-dependent (usually 5).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{bind}{address}
|
|
Bind the socket to \var{address}. The socket must not already
|
|
be bound. (The format of \var{address} depends on the address
|
|
family --- see above.)
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{accept}{}
|
|
Accept a connection. The socket must be bound to an address
|
|
and listening for connections. The return value is a pair
|
|
\code{(\var{conn}, \var{address})} where \var{conn} is a
|
|
\emph{new} socket object usable to send and receive data on
|
|
the connection, and \var{address} is the address bound to the
|
|
socket on the other end of the connection.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{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.
|
|
\end{methoddesc}
|
|
|
|
|
|
\subsection{asyncore Example basic HTTP client \label{asyncore-example}}
|
|
|
|
Here is a very basic HTTP client that uses the \class{dispatcher}
|
|
class to implement its socket handling:
|
|
|
|
\begin{verbatim}
|
|
import asyncore, socket
|
|
|
|
class http_client(asyncore.dispatcher):
|
|
|
|
def __init__(self, host, path):
|
|
asyncore.dispatcher.__init__(self)
|
|
self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
|
|
self.connect( (host, 80) )
|
|
self.buffer = 'GET %s HTTP/1.0\r\n\r\n' % path
|
|
|
|
def handle_connect(self):
|
|
pass
|
|
|
|
def handle_close(self):
|
|
self.close()
|
|
|
|
def handle_read(self):
|
|
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()
|
|
\end{verbatim}
|