From 0690bcf6151bb3c0f2b8c7c6d397c247e4b8bdf8 Mon Sep 17 00:00:00 2001 From: Fredrik Tolf Date: Sun, 12 Jan 2014 07:44:21 +0100 Subject: [PATCH] python: Updated documentation. --- python/doc/ashd-wsgi.doc | 90 ++++++++++++++++++++++++++++++++++++++++------ python/doc/scgi-wsgi.doc | 13 ++++++- python3/doc/ashd-wsgi3.doc | 90 ++++++++++++++++++++++++++++++++++++++++------ python3/doc/scgi-wsgi3.doc | 13 ++++++- 4 files changed, 182 insertions(+), 24 deletions(-) diff --git a/python/doc/ashd-wsgi.doc b/python/doc/ashd-wsgi.doc index f9dd1c2..566238c 100644 --- a/python/doc/ashd-wsgi.doc +++ b/python/doc/ashd-wsgi.doc @@ -7,7 +7,7 @@ ashd-wsgi - WSGI adapter for ashd(7) SYNOPSIS -------- -*ashd-wsgi* [*-hA*] [*-m* 'PDM-SPEC'] [*-p* 'MODPATH'] [*-l* 'LIMIT'] 'HANDLER-MODULE' ['ARGS'...] +*ashd-wsgi* [*-hAL*] [*-m* 'PDM-SPEC'] [*-p* 'MODPATH'] [*-t* 'HANDLING-MODEL'] 'HANDLER-MODULE' ['ARGS'...] DESCRIPTION ----------- @@ -21,7 +21,10 @@ section, below. 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. +between requests. More precisely, *ashd-wsgi* implements a couple of +slightly different ways to handle requests and threads, which can be +configured using the *-t* option, as described in the REQUEST HANDLING +section, below. The Python module that *ashd-wsgi* comes with also contains a standard handler module, `ashd.wsgidir`, which serves individual WSGI @@ -47,6 +50,12 @@ OPTIONS the WSGI application object. See the PROTOCOL section, below, for details. +*-L*:: + By default, *ashd-wsgi* sets up the Python logging with a + logging format and for logging to standard error. The *-L* + option suppresses that behavior, so that any handler module + may set up logging itself. + *-p* 'MODPATH':: Prepend 'MODPATH' to Python's `sys.path`; can be given multiple @@ -54,13 +63,10 @@ OPTIONS 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':: +*-t* 'HANDLING-MODEL':: - 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-wsgi* will assume that the - process is foobar and *abort*(3). + Specify the way *ashd-wsgi* handles requests. See below, under + REQUEST HANDLING. *-m* 'PDM-SPEC':: @@ -80,14 +86,75 @@ 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. +request, in which the WSGI application object is called (but see +below, under REQUEST HANDLING, for details). 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. +REQUEST HANDLING +---------------- + +*ashd-wsgi* can be configured to handle requests in various ways, +using the *-t* command-line option. The argument to the *-t* option +takes the form 'HANDLER'[*:*'PAR'[*=*'VAL'][(*,*'PAR'[*=*'VAL'])...]], +in order to specify the handler model, along with parameters to the +same (using the same syntax as the port specifications of +*htparser*(1)). The 'HANDLER' can be any of the following: + +*free*[*:max=*'MAX-THREADS'*,timeout=*'TIMEOUT']:: + + The *free* handler, which is the default, starts a new thread + for every incoming request, which runs the whole request in + its entirety, from running the WSGI handler function to + sending the contents of the response iterator. Optionally, + 'MAX-THREADS' may be specified to an integer, in which case no + more than that many request-handler threads will be allowed to + run at any one time (by default, any number of threads are + allowed to run, without limit). If further requests come in + while 'MAX-THREADS' handlers are running, the request dispatch + thread itself will block until one exits, making new requests + queue up in the socket over which they arrive, eventually + filling up its buffers if no threads exit, in turn making the + parent handler either block or receive *EAGAIN* errors. Also, + if 'MAX-THREADS' is specified, 'TIMEOUT' may also be + specified, to tell the dispatcher thread to never block more + than so many seconds for a handler thread to exit. If it is + forced to wait longer than 'TIMEOUT' seconds, it will assume + the whole process is somehow foobar and will *abort*(3). + +*rplex*[*:max=*'MAX-THREADS']:: + + The *rplex* handler starts a new thread for every incoming + request, but unlike the *free* handler, only the WSGI handler + function runs in that thread. Whenever any such thread, then, + returns its response iterator, all such iterators will be + passed to a single independent thread which sends their + contents to the clients, multiplexing between them whenever + their respective clients are ready to receive data. Like the + *free* handler, a 'MAX-THREADS' argument may be given to + specify how many handler threads are allowed to run at the + same time. The main advantage, compared to the *free* handler, + is that the *rplex* handler allows an arbitrary number of + response iterators to run simultaneously without tying up + handler threads, therefore not counting towards 'MAX-THREADS', + which may be necessary for applications handling large + files. However, it must be noted that no response iterators in + the application may block on returning data, since that would + also block all other running responses. Also, the *rplex* + handler does not support the `write` function returned by + `start_request`, according to the WSGI specification. + +*single*:: + + The *single* handler starts no threads at all, running all + received requests directly in the main dispatch thread. It is + probably not good for much except as the simplest possible + example of a request handling model. + EXAMPLES -------- @@ -99,6 +166,7 @@ child wsgidir exec ashd-wsgi ashd.wsgidir match filename *.wsgi + xset python-handler chain handler wsgidir -------- diff --git a/python/doc/scgi-wsgi.doc b/python/doc/scgi-wsgi.doc index 58ca3a7..08fc31e 100644 --- a/python/doc/scgi-wsgi.doc +++ b/python/doc/scgi-wsgi.doc @@ -7,7 +7,7 @@ scgi-wsgi - WSGI adapter for SCGI SYNOPSIS -------- -*scgi-wsgi* [*-hA*] [*-m* 'PDM-SPEC'] [*-p* 'MODPATH'] [*-T* \[HOST:]'PORT'] 'HANDLER-MODULE' ['ARGS'...] +*scgi-wsgi* [*-hAL*] [*-m* 'PDM-SPEC'] [*-p* 'MODPATH'] [*-t* 'HANDLING-MODEL'] [*-T* \[HOST:]'PORT'] 'HANDLER-MODULE' ['ARGS'...] DESCRIPTION ----------- @@ -41,11 +41,22 @@ OPTIONS the WSGI application object. See the PROTOCOL section of *ashd-wsgi*(1) for details. +*-L*:: + By default, *scgi-wsgi* sets up the Python logging with a + logging format and for logging to standard error. The *-L* + option suppresses that behavior, so that any handler module + may set up logging itself. + *-p* 'MODPATH':: Prepend 'MODPATH' to Python's `sys.path`; can be given multiple times. +*-t* 'HANDLING-MODEL':: + + Specify the way *scgi-wsgi* handles requests. See the REQUEST + HANDLING section of *ashd-wsgi*(1) for details. + *-T* \[HOST:]'PORT':: Instead of using a listening socket passed on standard input diff --git a/python3/doc/ashd-wsgi3.doc b/python3/doc/ashd-wsgi3.doc index 9d0123b..4350693 100644 --- a/python3/doc/ashd-wsgi3.doc +++ b/python3/doc/ashd-wsgi3.doc @@ -7,7 +7,7 @@ ashd-wsgi3 - WSGI adapter for ashd(7) SYNOPSIS -------- -*ashd-wsgi3* [*-hA*] [*-m* 'PDM-SPEC'] [*-p* 'MODPATH'] [*-l* 'LIMIT'] 'HANDLER-MODULE' ['ARGS'...] +*ashd-wsgi3* [*-hAL*] [*-m* 'PDM-SPEC'] [*-p* 'MODPATH'] [*-t* 'HANDLING-MODEL'] 'HANDLER-MODULE' ['ARGS'...] DESCRIPTION ----------- @@ -21,7 +21,10 @@ section, below. 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. +between requests. More precisely, *ashd-wsgi* implements a couple of +slightly different ways to handle requests and threads, which can be +configured using the *-t* option, as described in the REQUEST HANDLING +section, below. The Python module that *ashd-wsgi3* comes with also contains a standard handler module, `ashd.wsgidir`, which serves individual WSGI @@ -47,6 +50,12 @@ OPTIONS the WSGI application object. See the PROTOCOL section, below, for details. +*-L*:: + By default, *ashd-wsgi3* sets up the Python logging with a + logging format and for logging to standard error. The *-L* + option suppresses that behavior, so that any handler module + may set up logging itself. + *-p* 'MODPATH':: Prepend 'MODPATH' to Python's `sys.path`; can be given multiple @@ -54,13 +63,10 @@ OPTIONS 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':: +*-t* 'HANDLING-MODEL':: - 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). + Specify the way *ashd-wsgi* handles requests. See below, under + REQUEST HANDLING. *-m* 'PDM-SPEC':: @@ -80,14 +86,75 @@ 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. +request, in which the WSGI application object is called (but see +below, under REQUEST HANDLING, for details). 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. +REQUEST HANDLING +---------------- + +*ashd-wsgi3* can be configured to handle requests in various ways, +using the *-t* command-line option. The argument to the *-t* option +takes the form 'HANDLER'[*:*'PAR'[*=*'VAL'][(*,*'PAR'[*=*'VAL'])...]], +in order to specify the handler model, along with parameters to the +same (using the same syntax as the port specifications of +*htparser*(1)). The 'HANDLER' can be any of the following: + +*free*[*:max=*'MAX-THREADS'*,timeout=*'TIMEOUT']:: + + The *free* handler, which is the default, starts a new thread + for every incoming request, which runs the whole request in + its entirety, from running the WSGI handler function to + sending the contents of the response iterator. Optionally, + 'MAX-THREADS' may be specified to an integer, in which case no + more than that many request-handler threads will be allowed to + run at any one time (by default, any number of threads are + allowed to run, without limit). If further requests come in + while 'MAX-THREADS' handlers are running, the request dispatch + thread itself will block until one exits, making new requests + queue up in the socket over which they arrive, eventually + filling up its buffers if no threads exit, in turn making the + parent handler either block or receive *EAGAIN* errors. Also, + if 'MAX-THREADS' is specified, 'TIMEOUT' may also be + specified, to tell the dispatcher thread to never block more + than so many seconds for a handler thread to exit. If it is + forced to wait longer than 'TIMEOUT' seconds, it will assume + the whole process is somehow foobar and will *abort*(3). + +*rplex*[*:max=*'MAX-THREADS']:: + + The *rplex* handler starts a new thread for every incoming + request, but unlike the *free* handler, only the WSGI handler + function runs in that thread. Whenever any such thread, then, + returns its response iterator, all such iterators will be + passed to a single independent thread which sends their + contents to the clients, multiplexing between them whenever + their respective clients are ready to receive data. Like the + *free* handler, a 'MAX-THREADS' argument may be given to + specify how many handler threads are allowed to run at the + same time. The main advantage, compared to the *free* handler, + is that the *rplex* handler allows an arbitrary number of + response iterators to run simultaneously without tying up + handler threads, therefore not counting towards 'MAX-THREADS', + which may be necessary for applications handling large + files. However, it must be noted that no response iterators in + the application may block on returning data, since that would + also block all other running responses. Also, the *rplex* + handler does not support the `write` function returned by + `start_request`, according to the WSGI specification. + +*single*:: + + The *single* handler starts no threads at all, running all + received requests directly in the main dispatch thread. It is + probably not good for much except as the simplest possible + example of a request handling model. + EXAMPLES -------- @@ -99,6 +166,7 @@ child wsgidir exec ashd-wsgi3 ashd.wsgidir match filename *.wsgi + xset python-handler chain handler wsgidir -------- diff --git a/python3/doc/scgi-wsgi3.doc b/python3/doc/scgi-wsgi3.doc index 6c7d7db..d516859 100644 --- a/python3/doc/scgi-wsgi3.doc +++ b/python3/doc/scgi-wsgi3.doc @@ -7,7 +7,7 @@ scgi-wsgi3 - WSGI adapter for SCGI SYNOPSIS -------- -*scgi-wsgi3* [*-hA*] [*-m* 'PDM-SPEC'] [*-p* 'MODPATH'] [*-T* \[HOST:]'PORT'] 'HANDLER-MODULE' ['ARGS'...] +*scgi-wsgi3* [*-hAL*] [*-m* 'PDM-SPEC'] [*-p* 'MODPATH'] [*-t* 'HANDLING-MODEL'] [*-T* \[HOST:]'PORT'] 'HANDLER-MODULE' ['ARGS'...] DESCRIPTION ----------- @@ -41,11 +41,22 @@ OPTIONS the WSGI application object. See the PROTOCOL section of *ashd-wsgi*(1) for details. +*-L*:: + By default, *scgi-wsgi3* sets up the Python logging with a + logging format and for logging to standard error. The *-L* + option suppresses that behavior, so that any handler module + may set up logging itself. + *-p* 'MODPATH':: Prepend 'MODPATH' to Python's `sys.path`; can be given multiple times. +*-t* 'HANDLING-MODEL':: + + Specify the way *scgi-wsgi3* handles requests. See the REQUEST + HANDLING section of *ashd-wsgi3*(1) for details. + *-T* \[HOST:]'PORT':: Instead of using a listening socket passed on standard input -- 2.11.0