X-Git-Url: http://dolda2000.com/gitweb/?a=blobdiff_plain;f=python3%2Fdoc%2Fashd-wsgi3.doc;fp=python3%2Fdoc%2Fashd-wsgi3.doc;h=0af0882f6a9dbadc70589f0cac429fcb46012a92;hb=1f3d7aa314fa55a238be0940a1cd244e4671fc7d;hp=0000000000000000000000000000000000000000;hpb=c8301b0b38cae03a08ff8d11f0055f2353e86a41;p=ashd.git

diff --git a/python3/doc/ashd-wsgi3.doc b/python3/doc/ashd-wsgi3.doc
new file mode 100644
index 0000000..0af0882
--- /dev/null
+++ b/python3/doc/ashd-wsgi3.doc
@@ -0,0 +1,115 @@
+ashd-wsgi3(1)
+=============
+
+NAME
+----
+ashd-wsgi3 - WSGI adapter for ashd(7)
+
+SYNOPSIS
+--------
+*ashd-wsgi3* [*-hA*] [*-p* 'MODPATH'] [*-l* 'LIMIT'] 'HANDLER-MODULE' ['ARGS'...]
+
+DESCRIPTION
+-----------
+
+The *ashd-wsgi3* handler translates *ashd*(7) requests to WSGI
+requests, and passes them to a specified Python handler module. The
+precise Python convention for doing so is described in the PROTOCOL
+section, below.
+
+*ashd-wsgi3* is a persistent handler, as defined in *ashd*(7). It uses
+multithreaded dispatching in a single Python interpreter, which means
+that WSGI applications that use it need to be thread-safe, but that
+they can also share all Python data structures and global variables
+between requests.
+
+The Python module that *ashd-wsgi3* comes with also contains a
+standard handler module, `ashd.wsgidir`, which serves individual WSGI
+applications directly from the files in which they reside and as such
+makes this program useful as a *dirplex*(1) handler. Please see its
+Python documentation for further details.
+
+*ashd-wsgi3* requires the `ashd.proto` and `ashd.util` modules, which
+are only available for CPython. If you want to use some other Python
+implementation instead, you may want to use the *scgi-wsgi*(1) program
+instead, along with *callscgi*(1).
+
+OPTIONS
+-------
+
+*-h*::
+
+	Print a brief help message to standard output and exit.
+
+*-A*::
+
+	Use the convention used by Apache's mod_wsgi module to find
+	the WSGI application object. See the PROTOCOL section, below,
+	for details.
+
+*-p* 'MODPATH'::
+
+	Prepend 'MODPATH' to Python's `sys.path`; can be given multiple
+	times. Note that the working directory of *ashd-wsgi3* is not
+	on Python's module path by default, so if you want to use a
+	module in that directory, you will need to specify "`-p .`".
+
+*-l* 'LIMIT'::
+
+	Allow at most 'LIMIT' requests to run concurrently. If a new
+	request is made when 'LIMIT' requests are executing, the new
+	request will wait up to ten seconds for one of them to
+	complete; if none does, *ashd-wsgi3* will assume that the
+	process is foobar and *abort*(3).
+
+PROTOCOL
+--------
+
+When starting, *ashd-wsgi3* will attempt to import the module named by
+'HANDLER-MODULE', look for an object named `wmain` in that module,
+call that object passing the 'ARGS' (as Python strings) as positional
+parameters, and use the returned object as the WSGI application
+object. If the *-A* option was specified, it will look for an object
+named `application` instead of `wmain`, and use that object directly
+as the WSGI application object.
+
+When calling the WSGI application, a new thread is started for each
+request, in which the WSGI application object is called. All requests
+run in the same interpreter, so it is guaranteed that data structures
+and global variables can be shared between requests.
+
+The WSGI environment is the standard CGI environment, including the
+`SCRIPT_FILENAME` variable whenever the `X-Ash-File` header was
+included in the request.
+
+EXAMPLES
+--------
+
+The following *dirplex*(1) configuration can be used for serving WSGI
+modules directly from the filesystem.
+
+--------
+child wsgidir
+  exec ashd-wsgi3 ashd.wsgidir
+match
+  filename *.wsgi
+  handler wsgidir
+--------
+
+Since *ashd-wsgi3* is a persistent handler, it can be used directly as
+a root handler for *htparser*(1). For instance, if the directory
+`/srv/www/foo` contains a `wsgi.py` file, which declares a standard
+WSGI `application` object, it can be served with the following
+command:
+
+--------
+htparser plain:port=8080 -- ashd-wsgi3 -Ap /srv/www/foo wsgi
+--------
+
+AUTHOR
+------
+Fredrik Tolf <fredrik@dolda2000.com>
+
+SEE ALSO
+--------
+*scgi-wsgi3*(1), *ashd*(7), <http://wsgi.org/>