Added AMK's SocketServer docs.

1 files changed, 188 insertions, 0 deletions

diff --git a/Doc/libsocksvr.tex b/Doc/libsocksvr.tex
new file mode 100644
index 0000000..1e3cac3
--- /dev/null
+++ b/Doc/libsocksvr.tex
@@ -0,0 +1,188 @@
+\section{Standard Module \sectcode{SocketServer}}
+\stmodindex{SocketServer}
+
+The \code{SocketServer} module simplifies the task of writing network
+servers.  
+
+There are four basic server classes: \code{TCPServer} uses the
+Internet TCP protocol, which provides for continuous streams of data
+between the client and server.  \code{UDPServer} uses datagrams, which
+are discrete packets of information that may arrive out of order or be
+lost while in transit.  The more infrequently used
+\code{UnixStreamServer} and \code{UnixDatagramServer} classes are
+similar, but use Unix domain sockets; they're not available on
+non-Unix platforms.  For more details on network programming, consult
+a book such as W. Richard Steven's \emph{Unix Network Programming}_ or
+XXX (a Windows equivalent).
+
+These four classes process requests \dfn{synchronously}; each request
+must be completed before the next request can be started.  This isn't
+suitable if each request takes a long time to complete, because it
+requires a lot of computation, or because it returns a lot of data
+which the client is slow to process.  The solution is to create a
+separate process or thread to handle each request; the
+\code{ForkingMixIn} and \code{ThreadingMixIn} mix-in classes can be
+used to support asynchronous behaviour.
+
+Creating a server requires several steps.  First, you must create a
+request handler class by subclassing the \code{BaseRequestHandler}
+class and overriding its \code{handle()} method; this method will
+process incoming requests.  Second, you must instantiate one of the
+server classes, passing it the server's address and the request
+handler class.  Finally, call the \code{handle_request()} or
+\code{serve_forever()} method of the server object to process one or
+many requests.
+
+Server classes have the same external methods and attributes, no
+matter what network protocol they use:
+
+%XXX should data and methods be intermingled, or separate?
+% how should the distinction between class and instance variables be
+% drawn?
+
+\begin{funcdesc}{fileno}{}
+Return an integer file descriptor for the socket on which the server
+is listening.  This function is most commonly passed to
+\code{select.select()}, to allow monitoring multiple servers in the
+same process.
+\end{funcdesc}
+
+\begin{funcdesc}{handle_request}{}
+Process a single request.  This function calls the following methods
+in order: \code{get_request()}, \code{verify_request()}, and
+\code{process_request()}.  If the user-provided \code{handle()} method
+of the handler class raises an exception, the server's
+\code{handle_error()} method will be called.
+\end{funcdesc}
+
+\begin{funcdesc}{serve_forever}{}
+Handle an infinite number of requests.  This simply calls
+\code{handle_request()} inside an infinite loop.
+\end{funcdesc}
+
+\begin{datadesc}{address_family}
+The family of protocols to which the server's socket belongs.
+\code{socket.AF_INET} and \code{socket.AF_UNIX} are two possible values.
+\end{datadesc}
+
+\begin{datadesc}{RequestHandlerClass}
+The user-provided request handler class; an instance of this class is
+created for each request.
+\end{datadesc}
+
+\begin{datadesc}{server_address}
+The address on which the server is listening.  The format of addresses
+varies depending on the protocol family; see the documentation for the
+socket module for details.  For Internet protocols, this is a tuple
+containing a string giving the address, and an integer port number:
+\code{('127.0.0.1', 80)}, for example.
+\end{datadesc}
+
+\begin{datadesc}{socket}
+The socket object on which the server will listen for incoming requests.
+\end{datadesc}
+
+% XXX should class variables be covered before instance variables, or
+% vice versa?
+
+The server classes support the following class variables:
+
+\begin{datadesc}{request_queue_size}
+The size of the request queue.  If it takes a long time to process a
+single request, any requests that arrive while the server is busy are
+placed into a queue, up to \code{request_queue_size} requests.  Once
+the queue is full, further requests from clients will get a
+``Connection denied'' error.  The default value is usually 5, but this
+can be overridden by subclasses.
+\end{datadesc}
+
+\begin{datadesc}{socket_type}
+The type of socket used by the server; \code{socket.SOCK_STREAM} and
+\code{socket.SOCK_DGRAM} are two possible values.
+\end{datadesc}
+
+There are various server methods that can be overridden by subclasses
+of base server classes like \code{TCPServer}; these methods aren't
+useful to external users of the server object.
+
+% should the default implementations of these be documented, or should
+% it be assumed that the user will look at SocketServer.py?
+
+\begin{funcdesc}{finish_request}{}
+Actually processes the request by instantiating
+\code{RequestHandlerClass} and calling its \code{handle()} method.
+\end{funcdesc}
+
+\begin{funcdesc}{get_request}{}
+Must accept a request from the socket, and return a 2-tuple containing
+the \emph{new} socket object to be used to communicate with the
+client, and the client's address.
+\end{funcdesc}
+
+\begin{funcdesc}{handle_error}{request\, client_address}
+This function is called if the \code{RequestHandlerClass}'s
+\code{handle} method raises an exception.  The default action is to print
+the traceback to standard output and continue handling further requests.
+\end{funcdesc}
+
+\begin{funcdesc}{process_request}{request\, client_address}
+Calls \code{finish_request()} to create an instance of the
+\code{RequestHandlerClass}.  If desired, this function can create a new
+process or thread to handle the request; the \code{ForkingMixIn} and
+\code{ThreadingMixIn} classes do this.
+\end{funcdesc}
+
+% Is there any point in documenting the following two functions?
+% What would the purpose of overriding them be: initializing server
+% instance variables, adding new network families?
+
+\begin{funcdesc}{server_activate}{}
+Called by the server's constructor to activate the server.
+May be overridden.
+\end{funcdesc}
+
+\begin{funcdesc}{server_bind}{}
+Called by the server's constructor to bind the socket to the desired
+address.  May be overridden.
+\end{funcdesc}
+
+\begin{funcdesc}{verify_request}{request\, client_address}
+Must return a Boolean value; if the value is true, the request will be
+processed, and if it's false, the request will be denied.
+This function can be overridden to implement access controls for a server.
+The default implementation always return true.
+\end{funcdesc}
+
+The request handler class must define a new \code{handle} method, and
+can override any of the following methods.  A new instance is created
+for each request.
+
+\begin{funcdesc}{finish}{}
+Called after the \code{handle} method to perform any clean-up actions
+required.  The default implementation does nothing.  If \code{setup()}
+or \code{handle()} raise an exception, this function will not be called.
+\end{funcdesc}
+
+\begin{funcdesc}{handle}{}
+This function must do all the work required to service a request.
+Several instance attributes are available to it; the request is
+available as \code{self.request}; the client address as
+\code{self.client_request}; and the server instance as \code{self.server}, in
+case it needs access to per-server information.
+
+The type of \code{self.request} is different for datagram or stream
+services.  For stream services, \code{self.request} is a socket
+object; for datagram services, \code{self.request} is a string.
+However, this can be hidden by using the mix-in request handler
+classes
+\code{StreamRequestHandler} or \code{DatagramRequestHandler}, which
+override the \code{setup} and \code{finish} methods, and provides
+\code{self.rfile} and \code{self.wfile} attributes.  \code{self.rfile}
+and \code{self.wfile} can be read or written, respectively, to get the
+request data or return data to the client.
+\end{funcdesc}
+
+\begin{funcdesc}{setup}{}
+Called before the \code{handle} method to perform any initialization
+actions required.  The default implementation does nothing.
+\end{funcdesc}