+++ /dev/null
-"""Generic socket server classes.\r
-\r
-This module tries to capture the various aspects of defining a server:\r
-\r
-For socket-based servers:\r
-\r
-- address family:\r
- - AF_INET{,6}: IP (Internet Protocol) sockets (default)\r
- - AF_UNIX: Unix domain sockets\r
- - others, e.g. AF_DECNET are conceivable (see <socket.h>\r
-- socket type:\r
- - SOCK_STREAM (reliable stream, e.g. TCP)\r
- - SOCK_DGRAM (datagrams, e.g. UDP)\r
-\r
-For request-based servers (including socket-based):\r
-\r
-- client address verification before further looking at the request\r
- (This is actually a hook for any processing that needs to look\r
- at the request before anything else, e.g. logging)\r
-- how to handle multiple requests:\r
- - synchronous (one request is handled at a time)\r
- - forking (each request is handled by a new process)\r
- - threading (each request is handled by a new thread)\r
-\r
-The classes in this module favor the server type that is simplest to\r
-write: a synchronous TCP/IP server. This is bad class design, but\r
-save some typing. (There's also the issue that a deep class hierarchy\r
-slows down method lookups.)\r
-\r
-There are five classes in an inheritance diagram, four of which represent\r
-synchronous servers of four types:\r
-\r
- +------------+\r
- | BaseServer |\r
- +------------+\r
- |\r
- v\r
- +-----------+ +------------------+\r
- | TCPServer |------->| UnixStreamServer |\r
- +-----------+ +------------------+\r
- |\r
- v\r
- +-----------+ +--------------------+\r
- | UDPServer |------->| UnixDatagramServer |\r
- +-----------+ +--------------------+\r
-\r
-Note that UnixDatagramServer derives from UDPServer, not from\r
-UnixStreamServer -- the only difference between an IP and a Unix\r
-stream server is the address family, which is simply repeated in both\r
-unix server classes.\r
-\r
-Forking and threading versions of each type of server can be created\r
-using the ForkingMixIn and ThreadingMixIn mix-in classes. For\r
-instance, a threading UDP server class is created as follows:\r
-\r
- class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass\r
-\r
-The Mix-in class must come first, since it overrides a method defined\r
-in UDPServer! Setting the various member variables also changes\r
-the behavior of the underlying server mechanism.\r
-\r
-To implement a service, you must derive a class from\r
-BaseRequestHandler and redefine its handle() method. You can then run\r
-various versions of the service by combining one of the server classes\r
-with your request handler class.\r
-\r
-The request handler class must be different for datagram or stream\r
-services. This can be hidden by using the request handler\r
-subclasses StreamRequestHandler or DatagramRequestHandler.\r
-\r
-Of course, you still have to use your head!\r
-\r
-For instance, it makes no sense to use a forking server if the service\r
-contains state in memory that can be modified by requests (since the\r
-modifications in the child process would never reach the initial state\r
-kept in the parent process and passed to each child). In this case,\r
-you can use a threading server, but you will probably have to use\r
-locks to avoid two requests that come in nearly simultaneous to apply\r
-conflicting changes to the server state.\r
-\r
-On the other hand, if you are building e.g. an HTTP server, where all\r
-data is stored externally (e.g. in the file system), a synchronous\r
-class will essentially render the service "deaf" while one request is\r
-being handled -- which may be for a very long time if a client is slow\r
-to read all the data it has requested. Here a threading or forking\r
-server is appropriate.\r
-\r
-In some cases, it may be appropriate to process part of a request\r
-synchronously, but to finish processing in a forked child depending on\r
-the request data. This can be implemented by using a synchronous\r
-server and doing an explicit fork in the request handler class\r
-handle() method.\r
-\r
-Another approach to handling multiple simultaneous requests in an\r
-environment that supports neither threads nor fork (or where these are\r
-too expensive or inappropriate for the service) is to maintain an\r
-explicit table of partially finished requests and to use select() to\r
-decide which request to work on next (or whether to handle a new\r
-incoming request). This is particularly important for stream services\r
-where each client can potentially be connected for a long time (if\r
-threads or subprocesses cannot be used).\r
-\r
-Future work:\r
-- Standard classes for Sun RPC (which uses either UDP or TCP)\r
-- Standard mix-in classes to implement various authentication\r
- and encryption schemes\r
-- Standard framework for select-based multiplexing\r
-\r
-XXX Open problems:\r
-- What to do with out-of-band data?\r
-\r
-BaseServer:\r
-- split generic "request" functionality out into BaseServer class.\r
- Copyright (C) 2000 Luke Kenneth Casson Leighton <lkcl@samba.org>\r
-\r
- example: read entries from a SQL database (requires overriding\r
- get_request() to return a table entry from the database).\r
- entry is processed by a RequestHandlerClass.\r
-\r
-"""\r
-\r
-# Author of the BaseServer patch: Luke Kenneth Casson Leighton\r
-\r
-# XXX Warning!\r
-# There is a test suite for this module, but it cannot be run by the\r
-# standard regression test.\r
-# To run it manually, run Lib/test/test_socketserver.py.\r
-\r
-__version__ = "0.4"\r
-\r
-\r
-import socket\r
-import select\r
-import sys\r
-import os\r
-import errno\r
-try:\r
- import threading\r
-except ImportError:\r
- import dummy_threading as threading\r
-\r
-__all__ = ["TCPServer","UDPServer","ForkingUDPServer","ForkingTCPServer",\r
- "ThreadingUDPServer","ThreadingTCPServer","BaseRequestHandler",\r
- "StreamRequestHandler","DatagramRequestHandler",\r
- "ThreadingMixIn", "ForkingMixIn"]\r
-if hasattr(socket, "AF_UNIX"):\r
- __all__.extend(["UnixStreamServer","UnixDatagramServer",\r
- "ThreadingUnixStreamServer",\r
- "ThreadingUnixDatagramServer"])\r
-\r
-def _eintr_retry(func, *args):\r
- """restart a system call interrupted by EINTR"""\r
- while True:\r
- try:\r
- return func(*args)\r
- except (OSError, select.error) as e:\r
- if e.args[0] != errno.EINTR:\r
- raise\r
-\r
-class BaseServer:\r
-\r
- """Base class for server classes.\r
-\r
- Methods for the caller:\r
-\r
- - __init__(server_address, RequestHandlerClass)\r
- - serve_forever(poll_interval=0.5)\r
- - shutdown()\r
- - handle_request() # if you do not use serve_forever()\r
- - fileno() -> int # for select()\r
-\r
- Methods that may be overridden:\r
-\r
- - server_bind()\r
- - server_activate()\r
- - get_request() -> request, client_address\r
- - handle_timeout()\r
- - verify_request(request, client_address)\r
- - server_close()\r
- - process_request(request, client_address)\r
- - shutdown_request(request)\r
- - close_request(request)\r
- - handle_error()\r
-\r
- Methods for derived classes:\r
-\r
- - finish_request(request, client_address)\r
-\r
- Class variables that may be overridden by derived classes or\r
- instances:\r
-\r
- - timeout\r
- - address_family\r
- - socket_type\r
- - allow_reuse_address\r
-\r
- Instance variables:\r
-\r
- - RequestHandlerClass\r
- - socket\r
-\r
- """\r
-\r
- timeout = None\r
-\r
- def __init__(self, server_address, RequestHandlerClass):\r
- """Constructor. May be extended, do not override."""\r
- self.server_address = server_address\r
- self.RequestHandlerClass = RequestHandlerClass\r
- self.__is_shut_down = threading.Event()\r
- self.__shutdown_request = False\r
-\r
- def server_activate(self):\r
- """Called by constructor to activate the server.\r
-\r
- May be overridden.\r
-\r
- """\r
- pass\r
-\r
- def serve_forever(self, poll_interval=0.5):\r
- """Handle one request at a time until shutdown.\r
-\r
- Polls for shutdown every poll_interval seconds. Ignores\r
- self.timeout. If you need to do periodic tasks, do them in\r
- another thread.\r
- """\r
- self.__is_shut_down.clear()\r
- try:\r
- while not self.__shutdown_request:\r
- # XXX: Consider using another file descriptor or\r
- # connecting to the socket to wake this up instead of\r
- # polling. Polling reduces our responsiveness to a\r
- # shutdown request and wastes cpu at all other times.\r
- r, w, e = _eintr_retry(select.select, [self], [], [],\r
- poll_interval)\r
- if self in r:\r
- self._handle_request_noblock()\r
- finally:\r
- self.__shutdown_request = False\r
- self.__is_shut_down.set()\r
-\r
- def shutdown(self):\r
- """Stops the serve_forever loop.\r
-\r
- Blocks until the loop has finished. This must be called while\r
- serve_forever() is running in another thread, or it will\r
- deadlock.\r
- """\r
- self.__shutdown_request = True\r
- self.__is_shut_down.wait()\r
-\r
- # The distinction between handling, getting, processing and\r
- # finishing a request is fairly arbitrary. Remember:\r
- #\r
- # - handle_request() is the top-level call. It calls\r
- # select, get_request(), verify_request() and process_request()\r
- # - get_request() is different for stream or datagram sockets\r
- # - process_request() is the place that may fork a new process\r
- # or create a new thread to finish the request\r
- # - finish_request() instantiates the request handler class;\r
- # this constructor will handle the request all by itself\r
-\r
- def handle_request(self):\r
- """Handle one request, possibly blocking.\r
-\r
- Respects self.timeout.\r
- """\r
- # Support people who used socket.settimeout() to escape\r
- # handle_request before self.timeout was available.\r
- timeout = self.socket.gettimeout()\r
- if timeout is None:\r
- timeout = self.timeout\r
- elif self.timeout is not None:\r
- timeout = min(timeout, self.timeout)\r
- fd_sets = _eintr_retry(select.select, [self], [], [], timeout)\r
- if not fd_sets[0]:\r
- self.handle_timeout()\r
- return\r
- self._handle_request_noblock()\r
-\r
- def _handle_request_noblock(self):\r
- """Handle one request, without blocking.\r
-\r
- I assume that select.select has returned that the socket is\r
- readable before this function was called, so there should be\r
- no risk of blocking in get_request().\r
- """\r
- try:\r
- request, client_address = self.get_request()\r
- except socket.error:\r
- return\r
- if self.verify_request(request, client_address):\r
- try:\r
- self.process_request(request, client_address)\r
- except:\r
- self.handle_error(request, client_address)\r
- self.shutdown_request(request)\r
-\r
- def handle_timeout(self):\r
- """Called if no new request arrives within self.timeout.\r
-\r
- Overridden by ForkingMixIn.\r
- """\r
- pass\r
-\r
- def verify_request(self, request, client_address):\r
- """Verify the request. May be overridden.\r
-\r
- Return True if we should proceed with this request.\r
-\r
- """\r
- return True\r
-\r
- def process_request(self, request, client_address):\r
- """Call finish_request.\r
-\r
- Overridden by ForkingMixIn and ThreadingMixIn.\r
-\r
- """\r
- self.finish_request(request, client_address)\r
- self.shutdown_request(request)\r
-\r
- def server_close(self):\r
- """Called to clean-up the server.\r
-\r
- May be overridden.\r
-\r
- """\r
- pass\r
-\r
- def finish_request(self, request, client_address):\r
- """Finish one request by instantiating RequestHandlerClass."""\r
- self.RequestHandlerClass(request, client_address, self)\r
-\r
- def shutdown_request(self, request):\r
- """Called to shutdown and close an individual request."""\r
- self.close_request(request)\r
-\r
- def close_request(self, request):\r
- """Called to clean up an individual request."""\r
- pass\r
-\r
- def handle_error(self, request, client_address):\r
- """Handle an error gracefully. May be overridden.\r
-\r
- The default is to print a traceback and continue.\r
-\r
- """\r
- print '-'*40\r
- print 'Exception happened during processing of request from',\r
- print client_address\r
- import traceback\r
- traceback.print_exc() # XXX But this goes to stderr!\r
- print '-'*40\r
-\r
-\r
-class TCPServer(BaseServer):\r
-\r
- """Base class for various socket-based server classes.\r
-\r
- Defaults to synchronous IP stream (i.e., TCP).\r
-\r
- Methods for the caller:\r
-\r
- - __init__(server_address, RequestHandlerClass, bind_and_activate=True)\r
- - serve_forever(poll_interval=0.5)\r
- - shutdown()\r
- - handle_request() # if you don't use serve_forever()\r
- - fileno() -> int # for select()\r
-\r
- Methods that may be overridden:\r
-\r
- - server_bind()\r
- - server_activate()\r
- - get_request() -> request, client_address\r
- - handle_timeout()\r
- - verify_request(request, client_address)\r
- - process_request(request, client_address)\r
- - shutdown_request(request)\r
- - close_request(request)\r
- - handle_error()\r
-\r
- Methods for derived classes:\r
-\r
- - finish_request(request, client_address)\r
-\r
- Class variables that may be overridden by derived classes or\r
- instances:\r
-\r
- - timeout\r
- - address_family\r
- - socket_type\r
- - request_queue_size (only for stream sockets)\r
- - allow_reuse_address\r
-\r
- Instance variables:\r
-\r
- - server_address\r
- - RequestHandlerClass\r
- - socket\r
-\r
- """\r
-\r
- address_family = socket.AF_INET\r
-\r
- socket_type = socket.SOCK_STREAM\r
-\r
- request_queue_size = 5\r
-\r
- allow_reuse_address = False\r
-\r
- def __init__(self, server_address, RequestHandlerClass, bind_and_activate=True):\r
- """Constructor. May be extended, do not override."""\r
- BaseServer.__init__(self, server_address, RequestHandlerClass)\r
- self.socket = socket.socket(self.address_family,\r
- self.socket_type)\r
- if bind_and_activate:\r
- try:\r
- self.server_bind()\r
- self.server_activate()\r
- except:\r
- self.server_close()\r
- raise\r
-\r
- def server_bind(self):\r
- """Called by constructor to bind the socket.\r
-\r
- May be overridden.\r
-\r
- """\r
- if self.allow_reuse_address:\r
- self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)\r
- self.socket.bind(self.server_address)\r
- self.server_address = self.socket.getsockname()\r
-\r
- def server_activate(self):\r
- """Called by constructor to activate the server.\r
-\r
- May be overridden.\r
-\r
- """\r
- self.socket.listen(self.request_queue_size)\r
-\r
- def server_close(self):\r
- """Called to clean-up the server.\r
-\r
- May be overridden.\r
-\r
- """\r
- self.socket.close()\r
-\r
- def fileno(self):\r
- """Return socket file number.\r
-\r
- Interface required by select().\r
-\r
- """\r
- return self.socket.fileno()\r
-\r
- def get_request(self):\r
- """Get the request and client address from the socket.\r
-\r
- May be overridden.\r
-\r
- """\r
- return self.socket.accept()\r
-\r
- def shutdown_request(self, request):\r
- """Called to shutdown and close an individual request."""\r
- try:\r
- #explicitly shutdown. socket.close() merely releases\r
- #the socket and waits for GC to perform the actual close.\r
- request.shutdown(socket.SHUT_WR)\r
- except socket.error:\r
- pass #some platforms may raise ENOTCONN here\r
- self.close_request(request)\r
-\r
- def close_request(self, request):\r
- """Called to clean up an individual request."""\r
- request.close()\r
-\r
-\r
-class UDPServer(TCPServer):\r
-\r
- """UDP server class."""\r
-\r
- allow_reuse_address = False\r
-\r
- socket_type = socket.SOCK_DGRAM\r
-\r
- max_packet_size = 8192\r
-\r
- def get_request(self):\r
- data, client_addr = self.socket.recvfrom(self.max_packet_size)\r
- return (data, self.socket), client_addr\r
-\r
- def server_activate(self):\r
- # No need to call listen() for UDP.\r
- pass\r
-\r
- def shutdown_request(self, request):\r
- # No need to shutdown anything.\r
- self.close_request(request)\r
-\r
- def close_request(self, request):\r
- # No need to close anything.\r
- pass\r
-\r
-class ForkingMixIn:\r
-\r
- """Mix-in class to handle each request in a new process."""\r
-\r
- timeout = 300\r
- active_children = None\r
- max_children = 40\r
-\r
- def collect_children(self):\r
- """Internal routine to wait for children that have exited."""\r
- if self.active_children is None:\r
- return\r
-\r
- # If we're above the max number of children, wait and reap them until\r
- # we go back below threshold. Note that we use waitpid(-1) below to be\r
- # able to collect children in size(<defunct children>) syscalls instead\r
- # of size(<children>): the downside is that this might reap children\r
- # which we didn't spawn, which is why we only resort to this when we're\r
- # above max_children.\r
- while len(self.active_children) >= self.max_children:\r
- try:\r
- pid, _ = os.waitpid(-1, 0)\r
- self.active_children.discard(pid)\r
- except OSError as e:\r
- if e.errno == errno.ECHILD:\r
- # we don't have any children, we're done\r
- self.active_children.clear()\r
- elif e.errno != errno.EINTR:\r
- break\r
-\r
- # Now reap all defunct children.\r
- for pid in self.active_children.copy():\r
- try:\r
- pid, _ = os.waitpid(pid, os.WNOHANG)\r
- # if the child hasn't exited yet, pid will be 0 and ignored by\r
- # discard() below\r
- self.active_children.discard(pid)\r
- except OSError as e:\r
- if e.errno == errno.ECHILD:\r
- # someone else reaped it\r
- self.active_children.discard(pid)\r
-\r
- def handle_timeout(self):\r
- """Wait for zombies after self.timeout seconds of inactivity.\r
-\r
- May be extended, do not override.\r
- """\r
- self.collect_children()\r
-\r
- def process_request(self, request, client_address):\r
- """Fork a new subprocess to process the request."""\r
- self.collect_children()\r
- pid = os.fork()\r
- if pid:\r
- # Parent process\r
- if self.active_children is None:\r
- self.active_children = set()\r
- self.active_children.add(pid)\r
- self.close_request(request) #close handle in parent process\r
- return\r
- else:\r
- # Child process.\r
- # This must never return, hence os._exit()!\r
- try:\r
- self.finish_request(request, client_address)\r
- self.shutdown_request(request)\r
- os._exit(0)\r
- except:\r
- try:\r
- self.handle_error(request, client_address)\r
- self.shutdown_request(request)\r
- finally:\r
- os._exit(1)\r
-\r
-\r
-class ThreadingMixIn:\r
- """Mix-in class to handle each request in a new thread."""\r
-\r
- # Decides how threads will act upon termination of the\r
- # main process\r
- daemon_threads = False\r
-\r
- def process_request_thread(self, request, client_address):\r
- """Same as in BaseServer but as a thread.\r
-\r
- In addition, exception handling is done here.\r
-\r
- """\r
- try:\r
- self.finish_request(request, client_address)\r
- self.shutdown_request(request)\r
- except:\r
- self.handle_error(request, client_address)\r
- self.shutdown_request(request)\r
-\r
- def process_request(self, request, client_address):\r
- """Start a new thread to process the request."""\r
- t = threading.Thread(target = self.process_request_thread,\r
- args = (request, client_address))\r
- t.daemon = self.daemon_threads\r
- t.start()\r
-\r
-\r
-class ForkingUDPServer(ForkingMixIn, UDPServer): pass\r
-class ForkingTCPServer(ForkingMixIn, TCPServer): pass\r
-\r
-class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass\r
-class ThreadingTCPServer(ThreadingMixIn, TCPServer): pass\r
-\r
-if hasattr(socket, 'AF_UNIX'):\r
-\r
- class UnixStreamServer(TCPServer):\r
- address_family = socket.AF_UNIX\r
-\r
- class UnixDatagramServer(UDPServer):\r
- address_family = socket.AF_UNIX\r
-\r
- class ThreadingUnixStreamServer(ThreadingMixIn, UnixStreamServer): pass\r
-\r
- class ThreadingUnixDatagramServer(ThreadingMixIn, UnixDatagramServer): pass\r
-\r
-class BaseRequestHandler:\r
-\r
- """Base class for request handler classes.\r
-\r
- This class is instantiated for each request to be handled. The\r
- constructor sets the instance variables request, client_address\r
- and server, and then calls the handle() method. To implement a\r
- specific service, all you need to do is to derive a class which\r
- defines a handle() method.\r
-\r
- The handle() method can find the request as self.request, the\r
- client address as self.client_address, and the server (in case it\r
- needs access to per-server information) as self.server. Since a\r
- separate instance is created for each request, the handle() method\r
- can define arbitrary other instance variariables.\r
-\r
- """\r
-\r
- def __init__(self, request, client_address, server):\r
- self.request = request\r
- self.client_address = client_address\r
- self.server = server\r
- self.setup()\r
- try:\r
- self.handle()\r
- finally:\r
- self.finish()\r
-\r
- def setup(self):\r
- pass\r
-\r
- def handle(self):\r
- pass\r
-\r
- def finish(self):\r
- pass\r
-\r
-\r
-# The following two classes make it possible to use the same service\r
-# class for stream or datagram servers.\r
-# Each class sets up these instance variables:\r
-# - rfile: a file object from which receives the request is read\r
-# - wfile: a file object to which the reply is written\r
-# When the handle() method returns, wfile is flushed properly\r
-\r
-\r
-class StreamRequestHandler(BaseRequestHandler):\r
-\r
- """Define self.rfile and self.wfile for stream sockets."""\r
-\r
- # Default buffer sizes for rfile, wfile.\r
- # We default rfile to buffered because otherwise it could be\r
- # really slow for large data (a getc() call per byte); we make\r
- # wfile unbuffered because (a) often after a write() we want to\r
- # read and we need to flush the line; (b) big writes to unbuffered\r
- # files are typically optimized by stdio even when big reads\r
- # aren't.\r
- rbufsize = -1\r
- wbufsize = 0\r
-\r
- # A timeout to apply to the request socket, if not None.\r
- timeout = None\r
-\r
- # Disable nagle algorithm for this socket, if True.\r
- # Use only when wbufsize != 0, to avoid small packets.\r
- disable_nagle_algorithm = False\r
-\r
- def setup(self):\r
- self.connection = self.request\r
- if self.timeout is not None:\r
- self.connection.settimeout(self.timeout)\r
- if self.disable_nagle_algorithm:\r
- self.connection.setsockopt(socket.IPPROTO_TCP,\r
- socket.TCP_NODELAY, True)\r
- self.rfile = self.connection.makefile('rb', self.rbufsize)\r
- self.wfile = self.connection.makefile('wb', self.wbufsize)\r
-\r
- def finish(self):\r
- if not self.wfile.closed:\r
- try:\r
- self.wfile.flush()\r
- except socket.error:\r
- # An final socket error may have occurred here, such as\r
- # the local error ECONNABORTED.\r
- pass\r
- self.wfile.close()\r
- self.rfile.close()\r
-\r
-\r
-class DatagramRequestHandler(BaseRequestHandler):\r
-\r
- # XXX Regrettably, I cannot get this working on Linux;\r
- # s.recvfrom() doesn't return a meaningful client address.\r
-\r
- """Define self.rfile and self.wfile for datagram sockets."""\r
-\r
- def setup(self):\r
- try:\r
- from cStringIO import StringIO\r
- except ImportError:\r
- from StringIO import StringIO\r
- self.packet, self.socket = self.request\r
- self.rfile = StringIO(self.packet)\r
- self.wfile = StringIO()\r
-\r
- def finish(self):\r
- self.socket.sendto(self.wfile.getvalue(), self.client_address)\r
projects / mirror_edk2.git / blobdiff