X-Git-Url: http://git.kpe.io/?p=cl-modlisp.git;a=blobdiff_plain;f=doc%2Freadme.html;h=d2f4a791a99c5033341c668c3b96e921a5aec586;hp=e88ff1f152a798838160a38a18bfb7d2ea08c258;hb=HEAD;hpb=3cd1fc37754064befbc4e5e9050ed8849da3ce09
diff --git a/doc/readme.html b/doc/readme.html
index e88ff1f..d2f4a79 100644
--- a/doc/readme.html
+++ b/doc/readme.html
@@ -1,4 +1,27 @@
-cl-modlisp readmecl-modlisp Documentation
Overview
cl-modlisp provides the Lisp side of the interface to Marc Battyani's mod_lisp apache module (http://www.fractalconcept.com).
Features
- support of AllegroCL, CMUCL, SBCL with sb-thread, and Lispworks.
- listener and worker socket/process management so that shutting down the listener closes all related open sockets and terminates all related proceses.
- support for running multiple command processors on multiple ports.
- transparent support for precomputing the HTML or XML response to take advantage of HTTP/1.1's Keep-Alive feature. This is switchable with a single keyword argument to the macro with-ml-page.
- Demonstration processor included
Prerequisites
Supported Platforms
- Allegro v6.2
- CMUCL 18e
- Lispworks v4.2
- SBCL 0.8.1 with sb-thread (multi-threading)
Quickstart
- The easiest way to install is to use the Debian GNU/Linux operating system. Using the testing or unstable distributions, you can give the command:
apt-get install libapache-mod-lisp cl-modlisp cl-kmrcl
If you are not using Debian, you will need to download and install
-mod_lisp, cl-modlisp, and cl-kmrcl manually.
- Add something like the below to httpd.conf and then restart apache
LispServer 127.0.0.1 20123 "localhost"
AddHandler lisp-handler .lsp - Start your Lisp implementation and load cl-modlisp with
(asdf:operate 'asdf:load-op 'modlisp) - Start the server with
(ml:modlisp-start :port 20123) - Try some demostration pages
links http://localhost/fixed.lsp
links http://localhost/debug.lsp - Shutdown the all cl-modlisp servers with
(ml:modlisp-stop-all)
Usage
The demo.lisp file for some examples of using cl-modlisp.
\ No newline at end of file
+cl-modlisp readmecl-modlisp Documentation
Overview
cl-modlisp provides the Lisp side of the interface to Marc Battyani's mod_lisp apache module (http://www.fractalconcept.com).
Features
- support for AllegroCL, CMUCL, SBCL with sb-thread, and Lispworks.
- listener and worker socket/process management so that shutting down the listener closes all related open sockets and terminates all related proceses.
- support for running multiple command processors on multiple ports.
- transparent support for precomputing the HTML or XML response to take advantage of HTTP/1.1's Keep-Alive feature. This is switchable with a single keyword argument to the macro with-ml-page.
- Optional timeout of worker processes
- Two process models for flexibility
- Demonstration processor included
Prerequisites
Supported Platforms
- Allegro v6.2
- CMUCL 18e
- Lispworks v4.2
- SBCL 0.8.1 with sb-thread (multi-threading)
Quickstart
- The easiest way to install is to use the Debian GNU/Linux operating system. Using the testing or unstable distributions, you can give the command:
apt-get install libapache-mod-lisp cl-modlisp cl-kmrcl
If you are not using Debian, you will need to download and install
+mod_lisp, cl-modlisp, and cl-kmrcl manually.
- Add something like the below to httpd.conf and then restart apache
LispServer 127.0.0.1 20123 "localhost"
AddHandler lisp-handler .lsp
- Start your Lisp implementation and load cl-modlisp with
(asdf:operate 'asdf:load-op 'modlisp)
- Start the server with
(ml:modlisp-start :port 20123)
- Try some demostration pages
links http://localhost/fixed.lsp
links http://localhost/debug.lsp
- Shutdown the all cl-modlisp servers with
(ml:modlisp-stop-all)
Process Models
There are two process models
Each connection spawns a new thread
This is the default model. Each new connection to listener socket spawns a new connection. This allows for an arbitrary number of concurrent connections. This has advantages if the workers require a long execution time.
Fixed pool of workers
This model is selected by passing the number of worker processes to init/listener with the keyword number-fixed-workers. This model has a lower overhead since new processes are not created and destroyed with each connection. It has advantages when the workers have a short execution time.
Usage
The demo.lisp file for examples of using cl-modlisp.
Overview
cl-modlisp is a multi-threaded handler for HTTP requests forwarded by Marc Battyani's (http://www.fractalconcept.com) mod_lisp Apache module.
Design Goals
cl-modlisp is designed as a thin layer to dispatch a mod_lisp request with multi-platform compatibility. Currently, cl-modlisp supports SBCL [multithreaded], CMUCL, AllegroCL, and Lispworks.
Dispatch model
Extremely simple: All requests are forwarded to a single processor that is passed as a parameter to cl-modlisp's start-up function.
Configuration
All configuration is set by passing keyword arguments to
+modlisp-start
- port number - a number
- processor - function designator which will receive all requests
- processor-args - list of extra arguments to be passed to processor
- timeout - NIL means never timeout otherwise number of seconds
- catch-errors - non-NIL means to catch errors
- number-fixed-workers - NIL means to spawn a new worker process for each request
- remote-host-checker - optional function designator to check the remote host IP address. Used for filtering requests.
Processor function
This function receives an argument of the 'command' alist and any
+other arguments passed to modlisp-start as the :processor-args. The
+'command' alist is an associative list of keys and values received
+from modlisp. No preprocessing is done except that keys are converted
+from strings to keywords forced to the default implementation case.
Default Processor
The default processor is a simple demo command processor not intended for end-user.
URI Processing
None. The raw URL is the value of the :url key in the command alist.
Responses
Responses are written to modlisp:*modlisp-socket*. The raw HTTP/1.1 header needs to be generated by the application.
Utility functions
A few utility functions are provided
with-ml-page
Outputs the body of the macro along with the HTTP/1.1 headers. Supports both precomputing responses with keep-alive connections and also outputing response to socket as it is generated. The latter is useful for lengthye reponses in time or length. Also support setting the content-type (default "text/html") and arbitrary list of headers.
query-to-alist
Converts posted query to an alist. Doesn't handle multipart forms.
redirect-to-location
Known issues
- This application has been most tested on AllegroCL.
By design, is not practical an application platform. It is should have
+an API package wrapped around this library which supports useful
+features like processing URIs, dispatches, cookies, and querys [URI
+and single/multipart POSTs]
Rather than adding these features to cl-modlisp, I've been working on
+a library which uses a session-id and dispatch model based on Franz's
+webactions library. It also integrates my portable version of Franz's
+URI module and adds query processing similar on AllegroServer's
+request-query functions. This library can used with both cl-modlisp
+and AllegroServe as connectors. However, as this library has grown, it
+looks more and more like AllegroServe, I've begun to question the
+value of using this library compared to just using Portable
+AllegroServe with just my webactions-like session-id and dispatch
+processors. In my mind, the greatest advantage of using this library
+is that it is a much smaller task maintaining cross-implementation
+compatibility with the cl-modlisp connector version maintaining such
+compatibility with paserve. The disadvantage of this library is that I
+dislike cloning AllegroServe's query and cookie processing. I do so,
+though, because I think their API is quite reasonable. This library
+is currently driving http://umlisp.kpe.io/
\ No newline at end of file