WebKit.ThreadedAppServer | index /usr/local/share/webware/WebKit/ThreadedAppServer.py

`Threaded Application Server
The AppServer is the main process of WebKit. It handles requests for
servlets from webservers.
ThreadedAppServer uses a threaded model for handling multiple requests.
At one time there were other experimental execution models for AppServer,
but none of these were successful and have been removed.
The ThreadedAppServer/AppServer distinction is thus largely historical.
ThreadedAppServer takes the following command line arguments:
start: start the AppServer (default argument)
stop: stop the currently running Apperver
daemon: run as a daemon
ClassName.SettingName=value: change configuration settings
When started, AppServer records its pid in appserverpid.txt.`

Modules
`` |  |
WebKit.AppServer MiscUtils.Configurable WebUtils.Funcs Queue | WebUtils errno os re | select signal socket sys | threading time traceback

Classes
`` |  | WebKit.ASStreamOut.ASStreamOut TASASStreamOut WebKit.AutoReloadingAppServer.AutoReloadingAppServer(WebKit.AppServer.AppServer) ThreadedAppServer Handler AdapterHandler MonitorHandler exceptions.Exception NotEnoughDataError ProtocolError RestartAppServerError
class AdapterHandler(Handler)
`` | `Adapter handler. Handles the Adapter protocol (as used in mod_webkit, wkcgi, WebKit.cgi, HTTPAdapter, etc). This protocol passes a marshalled dictionary which contains the keys ``format`` and ``environ``. ``format`` is currently always the string ``CGI``, and ``environ`` is a dictionary of string: string, with values like those passed in the environment to a CGI request (QUERY_STRING, HTTP_HOST, etc). The handler adds one more key, ``input``, which contains a file object based off the socket, which contains the body of the request (the POST data, for instance). It's left to Application to handle that data.`
| Methods defined here: handleRequest(self) `Handle request. Creates the request dictionary, and creates a `TASASStreamOut` object for the response, then calls `Application.dispatchRawRequest`, which does the rest of the work (here we just clean up after).` makeInput(self) `Create a file-like object from the socket.` Data and other attributes defined here: protocolName = 'address' settingPrefix = 'Adapter' Methods inherited from Handler: __init__(self, server, serverAddress) `Create a new socket handler. Each handler is attached to a specific host and port, and of course to the AppServer.` activate(self, sock, requestID) `Activate the handler for processing the request. `sock` is the incoming socket that this handler will work with, and `requestID` is a serial number unique for each request. This isn't where work gets done -- the handler is queued after this, and work is done when `handleRequest` is called.` close(self) `Close the socket. Called when the handler is finished. Closes the socket and returns the handler to the pool of inactive handlers.` receiveDict(self) `Receive a dictionary from the socket. Utility function to receive a marshalled dictionary from the socket. Returns None if the request was empty.`
class Handler
`` | `A very general socket handler. Handler is an abstract superclass -- specific protocol implementations will subclass this. A Handler takes a socket to interact with, and creates a raw request. Handlers will be reused. When a socket is received `activate` will be called -- but the handler should not do anything, as it is still running in the main thread. The handler is put into a queue, and a worker thread picks it up and runs `handleRequest`, which subclasses should override. Several methods are provided which are typically used by subclasses.`
| Methods defined here: __init__(self, server, serverAddress) `Create a new socket handler. Each handler is attached to a specific host and port, and of course to the AppServer.` activate(self, sock, requestID) `Activate the handler for processing the request. `sock` is the incoming socket that this handler will work with, and `requestID` is a serial number unique for each request. This isn't where work gets done -- the handler is queued after this, and work is done when `handleRequest` is called.` close(self) `Close the socket. Called when the handler is finished. Closes the socket and returns the handler to the pool of inactive handlers.` handleRequest(self) `Subclasses should override this -- this is where work gets done.` receiveDict(self) `Receive a dictionary from the socket. Utility function to receive a marshalled dictionary from the socket. Returns None if the request was empty.`
class MonitorHandler(Handler)
`` | `Monitor server status. Monitor is a minimal service that accepts a simple protocol, and returns a value indicating the status of the server. The protocol passes a marshalled dict, much like the Adapter interface, which looks like ``{'format': 'XXX'}``, where XXX is a command (``STATUS`` or ``QUIT``). Responds with a simple string, either the number of requests we've received (for ``STATUS``) or ``OK`` for ``QUIT`` (which also stops the server).`
| Methods defined here: handleRequest(self) Data and other attributes defined here: protocolName = 'monitor' settingPrefix = 'Monitor' Methods inherited from Handler: __init__(self, server, serverAddress) `Create a new socket handler. Each handler is attached to a specific host and port, and of course to the AppServer.` activate(self, sock, requestID) `Activate the handler for processing the request. `sock` is the incoming socket that this handler will work with, and `requestID` is a serial number unique for each request. This isn't where work gets done -- the handler is queued after this, and work is done when `handleRequest` is called.` close(self) `Close the socket. Called when the handler is finished. Closes the socket and returns the handler to the pool of inactive handlers.` receiveDict(self) `Receive a dictionary from the socket. Utility function to receive a marshalled dictionary from the socket. Returns None if the request was empty.`
class NotEnoughDataError(exceptions.Exception)
`` |  | Methods inherited from exceptions.Exception: __getitem__(...) __init__(...) __str__(...)
class ProtocolError(exceptions.Exception)
`` |  | Methods inherited from exceptions.Exception: __getitem__(...) __init__(...) __str__(...)
class RestartAppServerError(exceptions.Exception)
`` | `Raised by DebugAppServer when needed.`
| Methods inherited from exceptions.Exception: __getitem__(...) __init__(...) __str__(...)
class TASASStreamOut(WebKit.ASStreamOut.ASStreamOut)
`` | `Response stream for ThreadedAppServer. The `TASASStreamOut` class streams to a given socket, so that when `flush` is called and the buffer is ready to be written, it sends the data from the buffer out on the socket. This is the response stream used for requests generated by ThreadedAppServer. TAS stands for ThreadedAppServer (AS for AppServer... a little redundant).`
| Methods defined here: __init__(self, sock) `Create stream. We get an extra `sock` argument, which is the socket which we'll stream output to (if we're streaming).` flush(self) `Flush stream. Calls `ASStreamOut.ASStreamOut.flush`, and if that returns True (indicating the buffer is full enough) then we send data from the buffer out on the socket.` Methods inherited from WebKit.ASStreamOut.ASStreamOut: autoCommit(self, val=0) `Get/Set the value of _autoCommit.` buffer(self) `Return accumulated data which has not yet been flushed. We want to be able to get at this data without having to call flush first, so that we can (for example) integrate automatic HTML validation.` bufferSize(self, size=8192) `Return the buffer size and set a new size if one is provided.` clear(self) `Try to clear any accumulated response data. Will fail if the response is already sommitted.` close(self) `Close this buffer. No more data may be sent.` closed(self) `Check whether we are closed to new data.` commit(self, autoCommit=1) `Called by the Response to tell us to go. If `_autoCommit` is True, then we will be placed into autoCommit mode.` committed(self) `Are we committed?` needCommit(self) `Request for commitment. Called by the `HTTPResponse` instance that is using this instance to ask if the response needs to be prepared to be delivered. The response should then commit it's headers, etc.` pop(self, count) `Remove count bytes from the front of the buffer.` prepend(self, charstr) `Add the attached string to front of the response buffer. Invalid if we are already committed.` size(self) `Return the current size of the data held here.` write(self, charstr) `Write a string to the buffer.`
class ThreadedAppServer(WebKit.AutoReloadingAppServer.AutoReloadingAppServer)
`` | `Threaded Application Server. `ThreadedAppServer` accepts incoming socket requests, spawns a new thread or reuses an existing one, then dispatches the request to the appropriate handler (e.g., an Adapter handler, HTTP handler, etc., one for each protocol). The transaction is connected directly to the socket, so that the response is sent directly (if streaming is used, like if you call ``response.flush()``). Thus the ThreadedAppServer packages the socket/response, rather than value being returned up the call chain.`
| Method resolution order: ThreadedAppServer WebKit.AutoReloadingAppServer.AutoReloadingAppServer WebKit.AppServer.AppServer WebKit.ConfigurableForServerSidePath.ConfigurableForServerSidePath MiscUtils.Configurable.Configurable WebKit.Object.Object __builtin__.object MiscUtils.NamedValueAccess.NamedValueAccess Methods defined here: __init__(self, path=None) `Setup the AppServer, create an initial thread pool (threads created with `spawnThread`), record the PID in a file, and add any enabled handlers (Adapter, HTTP, Monitor).` absorbThread(self, count=1) `Absorb a thread. We do this by putting a None on the Queue. When a thread gets it, that tells it to exit. We also keep track of the threads, so after killing threads we go through all the threads and find the thread(s) that have exited, so that we can take them out of the thread pool.` activeThreadCount(self) `Get a snapshot of the number of threads currently in use. Called from `updateThreadUsage`.` addSocketHandler(self, handlerClass, serverAddress=None) `Add socket handler. Adds a socket handler for `serverAddress` -- `serverAddress` is a tuple (*host*, *port*), where *host* is the interface to connect to (for instance, the IP address on a machine with multiple IP numbers), and *port* is the port (e.g. HTTP is on 80 by default, and Webware adapters use 8086 by default). The `handlerClass` is a subclass of `Handler`, and is used to handle the actual request -- usually returning control back to ThreadedAppServer in some fashion. See `Handler` for more.` address(self, settingPrefix) `Get host address. The address for the Adapter (Host/interface, and port), as taken from ``Configs/AppServer.config``, settings ``Host`` and ``AdapterPort``.` awakeSelect(self) `Awake the select() call. The ``select()`` in `mainloop()` is blocking, so when we shut down we have to make a connect to unblock it. Here's where we do that, called `shutDown`.` defaultConfig(self) delThread(self) `Delete thread. Invoked immediately by threadloop() as a hook for subclasses. This implementation does nothing and subclasses need not invoke super.` initThread(self) `Initialize thread. Invoked immediately by threadloop() as a hook for subclasses. This implementation does nothing and subclasses need not invoke super.` isPersistent(self) mainloop(self, timeout=1) `Main thread loop. This is the main thread loop that accepts and dispatches socket requests. It goes through a loop as long as ``self.running > 2``. Setting ``self.running = 2`` asks the the main loop to end. When the main loop is finished, it sets ``self.running = 1``. When the AppServer is completely down, it sets ``self.running = 0``. The loop waits for connections, then based on the connecting port it initiates the proper Handler (e.g., AdapterHandler, HTTPHandler). Handlers are reused when possible. The initiated handlers are put into a queue, and worker threads poll that queue to look for requests that need to be handled (worker threads use `threadloop`). Every so often (every 5 loops) it updates thread usage information (`updateThreadUsage`), and every ``MaxServerThreads`` * 2 loops it it will manage threads (killing or spawning new ones, in `manageThreadCount`).` manageThreadCount(self) `Adjust the number of threads in use. From information gleened from `updateThreadUsage`, we see about how many threads are being used, to see if we have too many threads or too few. Based on this we create or absorb threads.` shutDown(self) `Called on shutdown. Also calls `AppServer.shutDown`, but first closes all sockets and tells all the threads to die.` spawnThread(self) `Create a new worker thread. Worker threads poll with the `threadloop` method.` threadloop(self) `The main loop for worker threads. Worker threads poll the ``_requestQueue`` to find a request handler waiting to run. If they find a None in the queue, this thread has been selected to die, which is the way the loop ends. The handler object does all the work when its `handleRequest` method is called. `initThread` and `delThread` methods are called at the beginning and end of the thread loop, but they aren't being used for anything (future use as a hook).` updateThreadUsage(self) `Update the threadUseCounter list. Called periodically from `mainloop`.` Methods inherited from WebKit.AutoReloadingAppServer.AutoReloadingAppServer: activateAutoReload(self) `Start the monitor thread.` deactivateAutoReload(self) `Tell the monitor thread to stop. This should be considered as a request, not a demand.` fileMonitorThreadLoop(self) `This the the main loop for the monitoring thread. Runs in its own thread, polling the files for changes directly (i.e., going through every file that's being used and checking its last-modified time, seeing if it's been changed since it was initially loaded).` fileMonitorThreadLoopFAM(self, getmtime=<function getmtime>) `Monitoring thread loop, but using the FAM library.` monitorNewModule(self, filepath, mtime=None) `Add new file to be monitored. This is a callback which ImportSpy invokes to notify us of new files to monitor. This is only used when we are using FAM.` restart(self) `Do the actual restart. Call `shouldRestart` from outside the class.` restartIfNecessary(self) `Check if the app server should be restarted. This should be called regularly to see if a restart is required. The server can only restart from the main thread, other threads can't do the restart. So this polls to see if `shouldRestart` has been called.` shouldRestart(self) `Tell the main thread to restart the server.` Methods inherited from WebKit.AppServer.AppServer: application(self) `Return the Application singleton.` checkForInstall(self) `Check whether Webware was installed. Exits with an error message if Webware was not installed. Called from `__init__`.` closeThread(self) `This method is called when the shutdown sequence is initiated.` configFilename(self) `Return the name of the AppServer configuration file.` configReplacementValues(self) `Get config values that need to be escaped.` createApplication(self) `Create and return an application object. Invoked by __init__.` error(self, msg) `Output an error. Flushes stdout and stderr, prints the message to stderr and exits with code 1.` initiateShutdown(self) `Ask the master thread to begin the shutdown.` loadPlugIn(self, path) `Load and return the given plug-in. May return None if loading was unsuccessful (in which case this method prints a message saying so). Used by `loadPlugIns` (note the **s**).` loadPlugIns(self) `Load all plug-ins. A plug-in allows you to extend the functionality of WebKit without necessarily having to modify its source. Plug-ins are loaded by AppServer at startup time, just before listening for requests. See the docs in `WebKit.PlugIn` for more info.` numRequests(self) `Return the number of requests. Returns the number of requests received by this app server since it was launched.` plugIn(self, name, default=<class MiscUtils.NoDefault>) `Return the plug-in with the given name.` plugIns(self) `Return a list of the plug-ins loaded by the app server. Each plug-in is a Python package.` printStartUpMessage(self) `Invoked by __init__, prints a little intro.` readyForRequests(self) `Declare ready for getting requests. Should be invoked by subclasses when they are finally ready to accept requests. Records some stats and prints a message.` recordPID(self) `Save the pid of the AppServer to a file.` serverSidePath(self, path=None) `Return the absolute server-side path of the WebKit app server. If the optional path is passed in, then it is joined with the server side directory to form a path relative to the app server.` startTime(self) `Return the time the app server was started. The time is given as seconds, like time().` version(self) `Return WebKit version.` warning(self, msg) `Output a warning (not yet implemented).` webKitPath(self) `Return teh WebKit path.` webwarePath(self) `Return the Webware path.` Methods inherited from WebKit.ConfigurableForServerSidePath.ConfigurableForServerSidePath: setting(self, name, default=<class MiscUtils.NoDefault>) `Returns the setting, filtered by serverSidePath(), if the name ends with ``Filename`` or ``Dir``.` Methods inherited from MiscUtils.Configurable.Configurable: commandLineConfig(self) `Settings that came from the command line (via addCommandLineSetting).` config(self) `Returns the configuration of the object as a dictionary. This is a combination of defaultConfig() and userConfig(). This method caches the config.` configName(self) `Returns the name of the configuration file (the portion before the '.config'). This is used on the command-line.` hasSetting(self, name) printConfig(self, dest=None) `Prints the configuration to the given destination, which defaults to stdout. A fixed with font is assumed for aligning the values to start at the same column.` setSetting(self, name, value) userConfig(self) `Returns the user config overrides found in the optional config file, or {} if there is no such file. The config filename is taken from configFilename().` Methods inherited from WebKit.Object.Object: deprecated(self, method) `Output a deprecation warning. The implementation of WebKit sometimes invokes this method which prints a warning that the method you are using has been deprecated. This method expects that deprecated methods say so at the beginning of their doc string and terminate that msg with @. For example: DEPRECATED: Class.foo() on 01/24/01 in ver 0.5. Use Class.bar() instead. @ Putting this information in the doc string is important for accuracy in the generated docs. Example call: deprecated(self.foo)` Data and other attributes inherited from WebKit.Object.Object: __dict__ = <dictproxy object> `dictionary for instance variables (if defined)` __weakref__ = <attribute '__weakref__' of 'Object' objects> `list of weak references to the object (if defined)` Methods inherited from MiscUtils.NamedValueAccess.NamedValueAccess: hasValueForKey(self, key) `Returns true if the key is available, although that does not guarantee that there will not be errors caused by retrieving the key.` hasValueForName(self, keysString) resetKeyBindings(self) setValueForKey(self, key, value) `Suppose key is 'foo'. This method sets the value with the following precedence: 1. Public attributes before private attributes 2. Methods before non-methods More specifically, this method then uses one of the following: @@ 2000-03-04 ce: fill in ...or invokes handleUnknownSetKey().` valueForKey(self, key, default=<class MiscUtils.NoDefault>) `Suppose key is 'foo'. This method returns the value with the following precedence: 1. Methods before non-methods 2. Public attributes before private attributes More specifically, this method then returns one of the following: * foo() * _foo() * self.foo * self._foo ...or default, if it was specified, otherwise invokes and returns result of valueForUnknownKey(). Note that valueForUnknownKey(), normally returns an exception. See valueForName() which is a more advanced version of this method that allows multiple, qualified keys.` valueForKeySequence(self, listOfKeys, default=None) valueForName(self, keysString, default=None) `Returns the value for the given keysString. This is the more advanced version of valueForKey(), which can only handle single names. This method can handle 'foo', 'foo1.foo2', 'a.b.c.d', etc. It will traverse dictionaries if needed.` valueForUnknownKey(self, key, default) `# Errors` valuesForNames(self, keys, default=None, defaults=None, forgive=0, includeNames=0) `Returns a list of values that match the given keys, each of which is passed through valueForName() and so could be of the form 'a.b.c'. keys is a sequence. default is any kind of object. defaults is a sequence. forgive and includeNames is a flag. If default is not None, then it is substituted when a key is not found. Otherwise, if defaults is not None, then it's corresponding/parallel value for the current key is substituted when a key is not found. Otherwise, if forgive=1, then unknown keys simply don't produce any values. Otherwise, if default and defaults are None, and forgive=0, then the unknown keys will probably raise an exception through valueForUnknownKey() although that method can always return a final, default value. if keys is None, then None is returned. If keys is an empty list, then None is returned. Often these last four arguments are specified by key. Examples: names = ['origin.x', 'origin.y', 'size.width', 'size.height'] obj.valuesForNames(names) obj.valuesForNames(names, default=0.0) obj.valuesForNames(names, defaults=[0.0, 0.0, 100.0, 100.0]) obj.valuesForNames(names, forgive=0) @@ 2000-03-04 ce: includeNames is only supported when forgive=1. It should be supported for the other cases. It should be documented. It should be included in the test cases.`

Functions
`` |  | Lock = allocate_lock(...) `allocate_lock() -> lock object (allocate() is an obsolete synonym) Create a new lock object. See LockType.__doc__ for information about locks.` StringIO(...) `StringIO([s]) -- Return a StringIO-like stream for reading or writing` dumps(...) loads(...) main(args) `Command line interface. Run by `Launch`, this is the main entrance and command-line interface for ThreadedAppServer.` run(workDir=None) `Start the server (`ThreadedAppServer`). `workDir` is the server-side path for the server, which may not be the ``Webware/WebKit`` directory (though by default it is). After setting up the ThreadedAppServer we call `ThreadedAppServer.mainloop` to start the server main loop. It also catches exceptions as a last resort.` runMainLoopInThread() `# Determines whether the main look should run in another thread. # On Win NT/2K/XP, we run the mainloop in a different thread because # it's not safe for Ctrl-C to be caught while manipulating the queues. # It's not safe on Linux either, but there, it appears that Ctrl-C will # trigger an exception in ANY thread, so this fix doesn't help.` shutDown(signum, frame) `Signal handler for shutting down the server.`

Data
`` |  | DefaultConfig = {'AdapterPort': 8086, 'EnableAdapter': 1, 'EnableHTTP': 1, 'EnableMonitor': 0, 'HTTPPort': 8080, 'Host': '127.0.0.1', 'MaxServerThreads': 20, 'MinServerThreads': 5, 'MonitorPort': 8085, 'StartServerThreads': 10} SIGHUP = 1 SIGINT = 2 SIGTERM = 15 debug = 0 doesRunHandleExceptions = True intLength = 5 server = None settingRE = <_sre.SRE_Pattern object> usage = '\nThreadedAppServer takes the following command l...ettingName=value: change configuration settings\n\n'