python: Removed the -l option from the usage message, since it's only for compatiblity.
[ashd.git] / python3 / doc / ashd-wsgi3.doc
CommitLineData
1f3d7aa3
FT
1ashd-wsgi3(1)
2=============
173e0e9e
FT
3
4NAME
5----
1f3d7aa3 6ashd-wsgi3 - WSGI adapter for ashd(7)
173e0e9e
FT
7
8SYNOPSIS
9--------
d5ee5cde 10*ashd-wsgi3* [*-hA*] [*-m* 'PDM-SPEC'] [*-p* 'MODPATH'] [*-l* 'LIMIT'] 'HANDLER-MODULE' ['ARGS'...]
173e0e9e
FT
11
12DESCRIPTION
13-----------
14
1f3d7aa3 15The *ashd-wsgi3* handler translates *ashd*(7) requests to WSGI
173e0e9e
FT
16requests, and passes them to a specified Python handler module. The
17precise Python convention for doing so is described in the PROTOCOL
18section, below.
19
1f3d7aa3 20*ashd-wsgi3* is a persistent handler, as defined in *ashd*(7). It uses
173e0e9e
FT
21multithreaded dispatching in a single Python interpreter, which means
22that WSGI applications that use it need to be thread-safe, but that
23they can also share all Python data structures and global variables
24between requests.
25
1f3d7aa3
FT
26The Python module that *ashd-wsgi3* comes with also contains a
27standard handler module, `ashd.wsgidir`, which serves individual WSGI
173e0e9e
FT
28applications directly from the files in which they reside and as such
29makes this program useful as a *dirplex*(1) handler. Please see its
30Python documentation for further details.
31
1f3d7aa3 32*ashd-wsgi3* requires the `ashd.proto` and `ashd.util` modules, which
173e0e9e
FT
33are only available for CPython. If you want to use some other Python
34implementation instead, you may want to use the *scgi-wsgi*(1) program
35instead, along with *callscgi*(1).
36
37OPTIONS
38-------
39
40*-h*::
41
42 Print a brief help message to standard output and exit.
43
44*-A*::
45
46 Use the convention used by Apache's mod_wsgi module to find
47 the WSGI application object. See the PROTOCOL section, below,
48 for details.
49
50*-p* 'MODPATH'::
51
52 Prepend 'MODPATH' to Python's `sys.path`; can be given multiple
1f3d7aa3 53 times. Note that the working directory of *ashd-wsgi3* is not
173e0e9e
FT
54 on Python's module path by default, so if you want to use a
55 module in that directory, you will need to specify "`-p .`".
56
57*-l* 'LIMIT'::
58
59 Allow at most 'LIMIT' requests to run concurrently. If a new
60 request is made when 'LIMIT' requests are executing, the new
61 request will wait up to ten seconds for one of them to
1f3d7aa3 62 complete; if none does, *ashd-wsgi3* will assume that the
173e0e9e
FT
63 process is foobar and *abort*(3).
64
d5ee5cde
FT
65*-m* 'PDM-SPEC'::
66
67 If the PDM library is installed on the system, create a
e3aca55c 68 listening socket for connecting PDM clients according to
d5ee5cde
FT
69 'PDM-SPEC'.
70
173e0e9e
FT
71PROTOCOL
72--------
73
1f3d7aa3 74When starting, *ashd-wsgi3* will attempt to import the module named by
173e0e9e
FT
75'HANDLER-MODULE', look for an object named `wmain` in that module,
76call that object passing the 'ARGS' (as Python strings) as positional
77parameters, and use the returned object as the WSGI application
78object. If the *-A* option was specified, it will look for an object
79named `application` instead of `wmain`, and use that object directly
80as the WSGI application object.
81
82When calling the WSGI application, a new thread is started for each
83request, in which the WSGI application object is called. All requests
84run in the same interpreter, so it is guaranteed that data structures
85and global variables can be shared between requests.
86
87The WSGI environment is the standard CGI environment, including the
88`SCRIPT_FILENAME` variable whenever the `X-Ash-File` header was
89included in the request.
90
91EXAMPLES
92--------
93
94The following *dirplex*(1) configuration can be used for serving WSGI
95modules directly from the filesystem.
96
97--------
98child wsgidir
1f3d7aa3 99 exec ashd-wsgi3 ashd.wsgidir
173e0e9e
FT
100match
101 filename *.wsgi
102 handler wsgidir
103--------
104
1f3d7aa3 105Since *ashd-wsgi3* is a persistent handler, it can be used directly as
173e0e9e
FT
106a root handler for *htparser*(1). For instance, if the directory
107`/srv/www/foo` contains a `wsgi.py` file, which declares a standard
108WSGI `application` object, it can be served with the following
109command:
110
111--------
1f3d7aa3 112htparser plain:port=8080 -- ashd-wsgi3 -Ap /srv/www/foo wsgi
173e0e9e
FT
113--------
114
115AUTHOR
116------
117Fredrik Tolf <fredrik@dolda2000.com>
118
119SEE ALSO
120--------
1f3d7aa3 121*scgi-wsgi3*(1), *ashd*(7), <http://wsgi.org/>