- bknr-cvs@common-lisp.net - mailman3.common-lisp.net

[bknr-cvs] edi changed trunk/thirdparty/hunchentoot/doc/index.xml
by BKNR Commits 18 Feb '09

18 Feb '09

Revision: 4275 Author: edi URL: http://bknr.net/trac/changeset/4275 Checkpoint U trunk/thirdparty/hunchentoot/doc/index.xml Change set too large, please see URL above

1 0

[bknr-cvs] edi changed trunk/thirdparty/hunchentoot/doc/index.xml
by BKNR Commits 17 Feb '09

17 Feb '09

Revision: 4274 Author: edi URL: http://bknr.net/trac/changeset/4274 Checkpoint U trunk/thirdparty/hunchentoot/doc/index.xml Modified: trunk/thirdparty/hunchentoot/doc/index.xml =================================================================== --- trunk/thirdparty/hunchentoot/doc/index.xml 2009-02-17 22:59:48 UTC (rev 4273) +++ trunk/thirdparty/hunchentoot/doc/index.xml 2009-02-17 23:31:17 UTC (rev 4274) @@ -377,7 +377,7 @@ <clix:function generic='true' name='stop'> <clix:lambda-list>acceptor </clix:lambda-list> - <clix:returns>result + <clix:returns>acceptor </clix:returns> <clix:description>Stops <clix:arg>acceptor</clix:arg> so that it no longer accepts requests. @@ -667,7 +667,114 @@ </clix:subchapter> + <clix:subchapter name="taskmasters" title="Taskmasters"> +As a "normal" Hunchentoot user, you can completely ignore taskmasters +and skip this section. But if you're still reading, here are the +dirty details: Each <a href="#acceptors">acceptor</a> has a taskmaster +associated with it at creation time. It is the taskmaster's job to +distribute the work of accepting and handling incoming connections. +The acceptor calls the taskmaster if appropriate and the taskmaster +calls back into the acceptor. This is done using the generic +functions described in this and +the <a href="#acceptor-behaviour">previous</a> section. Hunchentoot +comes with two standard taskmaster implementations - one (which is the +default used on multi-threaded Lisps) which starts a new thread for +each incoming connection and one which handles all requests +sequentially. It should for example be relatively straightforward to +create a taskmaster which allocates threads from a fixed pool instead +of creating a new one for each connection. + +If you want to implement your own taskmasters, you should subclass +<clix:ref>TASKMASTER</clix:ref> and specialize the generic functions in this section. + + + <clix:class name='taskmaster'> + <clix:description>An instance of this class is responsible for +distributing the work of handling requests for its acceptor. +This is +an "abstract" class in the sense that usually only instances of +subclasses of <clix:ref>TASKMASTER</clix:ref> will be used. + </clix:description> + </clix:class> + + <clix:class name='one-thread-per-connection-taskmaster'> + <clix:description>A taskmaster that starts one thread for listening +to incoming requests and one thread for each incoming connection. + +This is the default taskmaster implementation for multi-threaded Lisp +implementations. + + </clix:description> + </clix:class> + + <clix:class name='single-threaded-taskmaster'> + <clix:description>A taskmaster that runs synchronously in the +thread where the <clix:ref>START</clix:ref> function was invoked (or +in the case of LispWorks in the thread started +by <a href="http://www.lispworks.com/documentation/lw51/LWRM/html/lwref-61.htm#marker-9…"><code>COMM:START-UP-SERVER</code></a>). +This is the simplest possible taskmaster implementation in that its +methods do nothing but calling their acceptor "sister" +methods - <clix:ref>EXECUTE-ACCEPTOR</clix:ref> calls <clix:ref>ACCEPT-CONNECTIONS</clix:ref>, +<clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref> calls <clix:ref>PROCESS-CONNECTION</clix:ref>. + </clix:description> + </clix:class> + + <clix:function generic='true' name='execute-acceptor'> + <clix:lambda-list>taskmaster + </clix:lambda-list> + <clix:returns>result + </clix:returns> + <clix:description>This is a callback called by the acceptor once it +has performed all initial processing to start listening for incoming +connections (see <clix:ref>START-LISTENING</clix:ref>). It usually calls the +<clix:ref>ACCEPT-CONNECTIONS</clix:ref> method of the acceptor, but depending on the +taskmaster instance the method might be called from a new thread. + </clix:description> + </clix:function> + + <clix:function generic='true' name='handle-incoming-connection'> + <clix:lambda-list>taskmaster socket + </clix:lambda-list> + <clix:returns>result + </clix:returns> + <clix:description>This function is called by the acceptor to start +processing of requests on a new incoming connection. <clix:arg>socket</clix:arg> is the +usocket instance that represents the new connection (or a socket +handle on LispWorks). The taskmaster starts processing requests on +the incoming connection by calling the <clix:ref>PROCESS-CONNECTION</clix:ref> +method of the acceptor instance. The <clix:arg>socket</clix:arg> argument is passed to +<clix:ref>PROCESS-CONNECTION</clix:ref> as an argument. + </clix:description> + </clix:function> + + <clix:function generic='true' name='shutdown'> + <clix:lambda-list>taskmaster + </clix:lambda-list> + <clix:returns>taskmaster + </clix:returns> + <clix:description>Shuts down the taskmaster, i.e. frees all resources +that were set up by it. For example, a multi-threaded taskmaster +might terminate all threads that are currently associated with it. +This function is called by the acceptor's <clix:ref>STOP</clix:ref> method. + </clix:description> + </clix:function> + + <clix:accessor generic='true' name='taskmaster-acceptor'> + <clix:lambda-list>taskmaster + </clix:lambda-list> + <clix:returns>acceptor + </clix:returns> + <clix:description> +This is an accessor for the slot of a <clix:ref>TASKMASTER</clix:ref> +object that links back to the <a href="#acceptors">acceptor</a> it is +associated with. + </clix:description> + </clix:accessor> + + </clix:subchapter> + + </clix:chapter> <clix:chapter name='dict' title='The HUNCHENTOOT dictionary'> @@ -1516,18 +1623,7 @@ <clix:description>Escapes the characters #\<, #\>, #\', #\", and #\& for HTML output. </clix:description> </clix:function> - <clix:function generic='true' name='execute-acceptor'> - <clix:lambda-list>taskmaster - </clix:lambda-list> - <clix:returns>result - </clix:returns> - <clix:description>This is a callback called by the acceptor once it -has performed all initial processing to start listening for incoming -connections (see START-LISTENING). It usually calls the -ACCEPT-CONNECTIONS method of the acceptor, but depending on the -taskmaster instance the method might be called from a new thread. - </clix:description> - </clix:function> + <clix:function name='get-parameter'> <clix:lambda-list>name <clix:lkw>optional @@ -1578,25 +1674,7 @@ TIME. </clix:description> </clix:function> - <clix:function generic='true' name='handle-incoming-connection'> - <clix:lambda-list>taskmaster socket - </clix:lambda-list> - <clix:returns>result - </clix:returns> - <clix:description>This function is called by Hunchentoot to start processing of -requests on a new incoming connection. SOCKET is the usocket instance -that represents the new connection (or a socket handle on LispWorks). -The taskmaster starts processing requests on the incoming -connection by calling the START-REQUEST-PROCESSING function of the -acceptor instance, taken from the ACCEPTOR slot in the taskmaster -instance. The SOCKET argument is passed to START-REQUEST-PROCESSING -as argument. -In a multi-threaded environment, the taskmaster runs this function -in a separate thread. In a single-threaded environment, this function -is called directly. - </clix:description> - </clix:function> <clix:function name='handle-static-file'> <clix:lambda-list>path <clix:lkw>optional @@ -1782,11 +1860,7 @@ <clix:description>Adds appropriate headers to completely prevent caching on most browsers. </clix:description> </clix:function> - <clix:class name='one-thread-per-connection-taskmaster'> - <clix:description>A taskmaster that starts one thread for listening -to incoming requests and one thread for each incoming connection. - </clix:description> - </clix:class> + <clix:function name='parameter'> <clix:lambda-list>name <clix:lkw>optional @@ -2449,26 +2523,6 @@ (case-sensitive) already exists, it is replaced. </clix:description> </clix:function> - <clix:function generic='true' name='shutdown'> - <clix:lambda-list>taskmaster - </clix:lambda-list> - <clix:returns>result - </clix:returns> - <clix:description>Shuts down the taskmaster, i.e. frees all resources -that were set up by it. For example, a multi-threaded taskmaster -might terminate all threads that are currently associated with it. - </clix:description> - </clix:function> - <clix:class name='single-threaded-taskmaster'> - <clix:description>A taskmaster that runs synchronously in the thread -where the START function was invoked (or in the case of LispWorks in -the thread started by COMM:START-UP-SERVER). This is the simplest -possible taskmaster implementation in that its methods do nothing but -calling their acceptor "sister" methods - EXECUTE-ACCEPTOR calls -ACCEPT-CONNECTIONS, HANDLE-INCOMING-CONNECTION calls -PROCESS-CONNECTION. - </clix:description> - </clix:class> <clix:function name='ssl-p'> <clix:lambda-list> @@ -2501,27 +2555,6 @@ </clix:description> </clix:function> - <clix:class name='taskmaster'> - <clix:description>An instance of this class is responsible for -distributing the work of handling requests when its acceptor - </clix:description> - </clix:class> - <clix:accessor generic='true' name='taskmaster-acceptor'> - <clix:lambda-list>taskmaster - </clix:lambda-list> - <clix:returns>result - </clix:returns> - <clix:description> - </clix:description> - </clix:accessor> - <clix:accessor specialized='(TASKMASTER)' name='taskmaster-acceptor'> - <clix:lambda-list>(taskmaster taskmaster) - </clix:lambda-list> - <clix:returns>result - </clix:returns> - <clix:description> - </clix:description> - </clix:accessor> <clix:function name='url-decode'> <clix:lambda-list>string <clix:lkw>optional

1 0

[bknr-cvs] edi changed trunk/thirdparty/hunchentoot/doc/index.xml
by BKNR Commits 17 Feb '09

17 Feb '09

Revision: 4273 Author: edi URL: http://bknr.net/trac/changeset/4273 Checkpoint U trunk/thirdparty/hunchentoot/doc/index.xml Modified: trunk/thirdparty/hunchentoot/doc/index.xml =================================================================== --- trunk/thirdparty/hunchentoot/doc/index.xml 2009-02-17 22:23:13 UTC (rev 4272) +++ trunk/thirdparty/hunchentoot/doc/index.xml 2009-02-17 22:59:48 UTC (rev 4273) @@ -563,6 +563,111 @@ </clix:subchapter> + <clix:subchapter name="acceptor-behaviour" title="Acceptor behaviour"> + +If you want to modify what acceptors do, you should +subclass <clix:ref>ACCEPTOR</clix:ref> +(or <clix:ref>SSL-ACCEPTOR</clix:ref>) and specialize the generic +functions that constitute their behaviour. The life of an acceptor +looks like this: It is started with the function <clix:ref>START</clix:ref> which +immediately calls <clix:ref>START-LISTENING</clix:ref> and then applies the function +<clix:ref>EXECUTE-ACCEPTOR</clix:ref> to +its <a href="#taskmasters">taskmaster</a>. This function will +eventually call <clix:ref>ACCEPT-CONNECTIONS</clix:ref> which is +responsible for settings things up to wait for clients to connect. +For each connection which comes +in, <clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref> is applied to the +taskmaster which will call <clix:ref>PROCESS-CONNECTION</clix:ref>. +<clix:ref>PROCESS-CONNECTION</clix:ref> +calls <clix:ref>INITIALIZE-CONNECTION-STREAM</clix:ref> before it does +anything else, then it selects and calls a function which handles +the <a href="#requests">request</a>, and finally it sends +the <a href="#replies">reply</a> to the client before it +calls <clix:ref>RESET-CONNECTION-STREAM</clix:ref>. If the connection +is persistent, this procedure is repeated (except for the +intialization step) in a loop until the connection is closed. The +acceptor is stopped with <clix:ref>STOP</clix:ref>. + + +If you just want to use the standard acceptors that come with +Hunchentoot, you don't need to know anything about the functions +listed in this section. + + + <clix:function generic='true' name='start-listening'> + <clix:lambda-list>acceptor + </clix:lambda-list> + <clix:returns>| + </clix:returns> + <clix:description>Sets up a listen socket for the given acceptor and +enables it to listen to incoming connections. This function is called +from the thread that starts the acceptor initially and may return +errors resulting from the listening operation (like 'address in use' +or similar). + </clix:description> + </clix:function> + + <clix:function generic='true' name='accept-connections'> + <clix:lambda-list>acceptor + </clix:lambda-list> + <clix:returns>nil + </clix:returns> + <clix:description>In a loop, accepts a connection and hands it over +to the acceptor's taskmaster for processing using +<clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref>. On LispWorks, this +function returns immediately, on other Lisps it returns only once the +acceptor has been stopped. + </clix:description> + </clix:function> + + <clix:function generic='true' name='process-connection'> + <clix:lambda-list>acceptor socket + </clix:lambda-list> + <clix:returns>nil + </clix:returns> + <clix:description>This function is called by the taskmaster when a +new client connection has been established. Its arguments are the +<clix:ref>ACCEPTOR</clix:ref> object and a LispWorks socket handle or a usocket socket +stream object in <clix:arg>socket</clix:arg>. It reads the request headers, sets up the +<a href="#requests">request</a> and <a href="#replies">reply</a> +objects, and hands over to (the unexported +function) <code>PROCESS-REQUEST</code> which selects and calls a +handler for the request and sends its reply to the client. This is +done in a loop until the stream has to be closed or until a connection +timeout occurs. + </clix:description> + </clix:function> + + <clix:function generic='true' name='initialize-connection-stream'> + <clix:lambda-list>acceptor stream + </clix:lambda-list> + <clix:returns>stream + </clix:returns> + <clix:description>Can be used to modify the stream which is used +to communicate between client and server before the request is read. +The default method of <clix:ref>ACCEPTOR</clix:ref> does nothing, but +see for example the method defined +for <clix:ref>SSL-ACCEPTOR</clix:ref>. All methods of this generic +function must return the stream to use. + </clix:description> + </clix:function> + + <clix:function generic='true' name='reset-connection-stream'> + <clix:lambda-list>acceptor stream + </clix:lambda-list> + <clix:returns>stream + </clix:returns> + <clix:description>Resets the stream which is used to communicate +between client and server after one request has been served so that it +can be used to process the next request. This generic function is +called after a request has been processed and must return the +stream. + </clix:description> + </clix:function> + + </clix:subchapter> + + </clix:chapter> <clix:chapter name='dict' title='The HUNCHENTOOT dictionary'> @@ -1635,18 +1740,7 @@ format control and arguments. </clix:description> </clix:function> - <clix:function generic='true' name='initialize-connection-stream'> - <clix:lambda-list>acceptor stream - </clix:lambda-list> - <clix:returns>result - </clix:returns> - <clix:description>Can be used to modify the stream which is used to -communicate between client and server before the request is read. The -default method of ACCEPTOR does nothing, but see for example the -method defined for SSL-ACCEPTOR. All methods of this generic function -must return the stream to use. - </clix:description> - </clix:function> + <clix:function name='log-message'> <clix:lambda-list>log-level format-string <clix:lkw>rest @@ -1752,20 +1846,7 @@ object REQUEST. </clix:description> </clix:function> - <clix:function generic='true' name='process-connection'> - <clix:lambda-list>acceptor socket - </clix:lambda-list> - <clix:returns>result - </clix:returns> - <clix:description>This function is called by the taskmaster when a -new client connection has been established. Its arguments are the -ACCEPTOR object and a LispWorks socket handle or a usocket socket -stream object in SOCKET. It reads the request headers, sets up the -request and reply objects, and hands over to PROCESS-REQUEST. This is -done in a loop until the stream has to be closed or until a connection -timeout occurs. - </clix:description> - </clix:function> + <clix:function name='query-string*'> <clix:lambda-list> <clix:lkw>optional @@ -2063,18 +2144,7 @@ (see RFC 2617) for the realm REALM. </clix:description> </clix:function> - <clix:function generic='true' name='reset-connection-stream'> - <clix:lambda-list>acceptor stream - </clix:lambda-list> - <clix:returns>result - </clix:returns> - <clix:description>Resets the stream which is used to communicate -between client and server after one request has been served so that it -can be used to process the next request. This generic function is -called after a request has been processed and must return the -stream. - </clix:description> - </clix:function> + <clix:function name='reset-session-secret'> <clix:lambda-list> </clix:lambda-list> @@ -2419,18 +2489,7 @@ connections. Returns the acceptor. </clix:description> </clix:function> - <clix:function generic='true' name='start-listening'> - <clix:lambda-list>acceptor - </clix:lambda-list> - <clix:returns>result - </clix:returns> - <clix:description>Sets up a listen socket for the given ACCEPTOR and -enables it to listen to incoming connections. This function is called -from the thread that starts the acceptor initially and may return -errors resulting from the listening operation (like 'address in use' -or similar). - </clix:description> - </clix:function> + <clix:function name='start-session'> <clix:lambda-list> </clix:lambda-list>

1 0

[bknr-cvs] edi changed trunk/thirdparty/hunchentoot/
by BKNR Commits 17 Feb '09

17 Feb '09

Revision: 4272 Author: edi URL: http://bknr.net/trac/changeset/4272 Checkpoint U trunk/thirdparty/hunchentoot/doc/clixdoc.xsl U trunk/thirdparty/hunchentoot/doc/index.xml U trunk/thirdparty/hunchentoot/specials.lisp U trunk/thirdparty/hunchentoot/test/script.lisp Change set too large, please see URL above

1 0

[bknr-cvs] edi changed trunk/thirdparty/documentation-template/output.lisp
by BKNR Commits 17 Feb '09

17 Feb '09

Revision: 4271 Author: edi URL: http://bknr.net/trac/changeset/4271 Not all functions are accessors... U trunk/thirdparty/documentation-template/output.lisp Modified: trunk/thirdparty/documentation-template/output.lisp =================================================================== --- trunk/thirdparty/documentation-template/output.lisp 2009-02-17 21:28:19 UTC (rev 4270) +++ trunk/thirdparty/documentation-template/output.lisp 2009-02-17 21:31:28 UTC (rev 4271) @@ -150,7 +150,7 @@ (setq other-entries (remove writer other-entries))) (t (with-html-output (*doc-output* nil :indent 2) - (:|clix:accessor| + (:|clix:function| :generic (and genericp "true") :specialized specializers :name (string-downcase symbol)

1 0

[bknr-cvs] edi changed trunk/thirdparty/hunchentoot/doc/index.xml
by BKNR Commits 17 Feb '09

17 Feb '09

Revision: 4270 Author: edi URL: http://bknr.net/trac/changeset/4270 Checkpoint U trunk/thirdparty/hunchentoot/doc/index.xml Change set too large, please see URL above

1 0

[bknr-cvs] edi changed trunk/thirdparty/hunchentoot/doc/index.xml
by BKNR Commits 17 Feb '09

17 Feb '09

Revision: 4269 Author: edi URL: http://bknr.net/trac/changeset/4269 Starting with the HTML documentation... U trunk/thirdparty/hunchentoot/doc/index.xml Change set too large, please see URL above

1 0

[bknr-cvs] edi changed trunk/thirdparty/documentation-template/output.lisp
by BKNR Commits 17 Feb '09

17 Feb '09

Revision: 4268 Author: edi URL: http://bknr.net/trac/changeset/4268 Fix typo U trunk/thirdparty/documentation-template/output.lisp Modified: trunk/thirdparty/documentation-template/output.lisp =================================================================== --- trunk/thirdparty/documentation-template/output.lisp 2009-02-17 07:40:57 UTC (rev 4267) +++ trunk/thirdparty/documentation-template/output.lisp 2009-02-17 20:45:14 UTC (rev 4268) @@ -249,7 +249,7 @@ " package in alphabetical order linked to their corresponding documentation entries:" (:|clix:index|)) - (:|clix:chapter| :name "ack" :title "Ackknowledgements" + (:|clix:chapter| :name "ack" :title "Acknowledgements" (:p "This documentation was prepared with " (:a :href "http://weitz.de/documentation-template/" "DOCUMENTATION-TEMPLATE")))

1 0

[bknr-cvs] edi changed trunk/thirdparty/hunchentoot/doc/index.xml
by BKNR Commits 17 Feb '09

17 Feb '09

Revision: 4267 Author: edi URL: http://bknr.net/trac/changeset/4267 More U trunk/thirdparty/hunchentoot/doc/index.xml Modified: trunk/thirdparty/hunchentoot/doc/index.xml =================================================================== --- trunk/thirdparty/hunchentoot/doc/index.xml 2009-02-17 07:35:16 UTC (rev 4266) +++ trunk/thirdparty/hunchentoot/doc/index.xml 2009-02-17 07:40:57 UTC (rev 4267) @@ -2614,7 +2614,9 @@ listener, type <pre>(hunchentoot-test:test-hunchentoot "http://localhost:4242")</pre> You will see some diagnostic output and a summary line that - reports whether any tests have failed. + reports whether any tests have failed. (You can also use the + example certificate and key files in the test directory and + start and test an https server instead.) <clix:function name="hunchentoot-test:test-hunchentoot">

1 0

[bknr-cvs] edi changed trunk/thirdparty/hunchentoot/doc/index.xml
by BKNR Commits 17 Feb '09

17 Feb '09

Revision: 4266 Author: edi URL: http://bknr.net/trac/changeset/4266 Some doc additions while I'm waiting for a database U trunk/thirdparty/hunchentoot/doc/index.xml Modified: trunk/thirdparty/hunchentoot/doc/index.xml =================================================================== --- trunk/thirdparty/hunchentoot/doc/index.xml 2009-02-16 23:59:29 UTC (rev 4265) +++ trunk/thirdparty/hunchentoot/doc/index.xml 2009-02-17 07:35:16 UTC (rev 4266) @@ -2663,16 +2663,13 @@ Unfortunately, Jeff is at least as busy as I am so he didn't - find the time to finish a full release. But in spring 2004 I + find the time to finish a full release. But in spring 2004 I needed a documented version of the code for a client of mine who thought it would be good if the toolkit were publicly available under an open source license. So I took Jeff's code, refactored again (to sync with the changes I had done in the meantime), and added documentation. This resulted in TBNL 0.1.0 (which - initially required mod_lisp as its front-end). Jeff's code - (which includes a lot more stuff that I didn't use) is still - available from his own - website <a href="http://tbnl.org/">tbnl.org</a>. + initially required mod_lisp as its front-end). In March 2005, Bob Hutchinson sent patches which enabled TBNL to @@ -2690,16 +2687,20 @@ most of TBNL and replaces it completely. - Hunchentoot 1.0.0, released in May 2008, is again a major + Hunchentoot 1.0.0, released in February 2009, is again a major rewrite and should be considered work in progress. It moved to - using the usocket network portability library and Bordeaux - Threads for threading, thereby removing most of the platform - dependent code in the Hunchentoot code. Threading behavior was - made controllable by the <clix:arg>threaded</clix:arg> keyword - argument - to <clix:ref>START-SERVER</clix:ref>. <a href="http://www.cliki.net/mod_lisp">mod_lisp</a> - support was removed in this release to simplify the code base - and due to the lack of interest. A significant part of the 1.0.0 + using + the <a href="http://common-lisp.net/project/usocket/">usocket</a> + and <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux + Threads</a> for non-LispWorks Lisps, thereby removing most of + the platform dependent code. Threading behaviour was made + controllable through the introduction of + taskmasters. <a href="http://www.cliki.net/mod_lisp">mod_lisp</a> + support and several other things were removed in this release to + simplify the code base (and partly due to the lack of interest). + Several architectural changes (lots of them not + backwards-compatible) were made to ease customization of + Hunchentoot's behaviour. A significant part of the 1.0.0 redesign was done by <a href="http://netzhansa.blogspot.com/">Hans Hübner</a>.

1 0