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-listacceptor </clix:lambda-list> - clix:returnsresult + clix:returnsacceptor </clix:returns> clix:descriptionStops clix:argacceptor</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. +<p> +If you want to implement your own taskmasters, you should subclass +clix:refTASKMASTER</clix:ref> and specialize the generic functions in this section. +</p> + + <clix:class name='taskmaster'> + clix:descriptionAn 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:refTASKMASTER</clix:ref> will be used. + </clix:description> + </clix:class> + + <clix:class name='one-thread-per-connection-taskmaster'> + clix:descriptionA taskmaster that starts one thread for listening +to incoming requests and one thread for each incoming connection. +<p> +This is the default taskmaster implementation for multi-threaded Lisp +implementations. +</p> + </clix:description> + </clix:class> + + <clix:class name='single-threaded-taskmaster'> + clix:descriptionA taskmaster that runs synchronously in the +thread where the clix:refSTART</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-910861"><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:refEXECUTE-ACCEPTOR</clix:ref> calls clix:refACCEPT-CONNECTIONS</clix:ref>, +clix:refHANDLE-INCOMING-CONNECTION</clix:ref> calls clix:refPROCESS-CONNECTION</clix:ref>. + </clix:description> + </clix:class> + + <clix:function generic='true' name='execute-acceptor'> + clix:lambda-listtaskmaster + </clix:lambda-list> + clix:returnsresult + </clix:returns> + clix:descriptionThis is a callback called by the acceptor once it +has performed all initial processing to start listening for incoming +connections (see clix:refSTART-LISTENING</clix:ref>). It usually calls the +clix:refACCEPT-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-listtaskmaster socket + </clix:lambda-list> + clix:returnsresult + </clix:returns> + clix:descriptionThis function is called by the acceptor to start +processing of requests on a new incoming connection. clix:argsocket</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:refPROCESS-CONNECTION</clix:ref> +method of the acceptor instance. The clix:argsocket</clix:arg> argument is passed to +clix:refPROCESS-CONNECTION</clix:ref> as an argument. + </clix:description> + </clix:function> + + <clix:function generic='true' name='shutdown'> + clix:lambda-listtaskmaster + </clix:lambda-list> + clix:returnstaskmaster + </clix:returns> + clix:descriptionShuts 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:refSTOP</clix:ref> method. + </clix:description> + </clix:function> + + <clix:accessor generic='true' name='taskmaster-acceptor'> + clix:lambda-listtaskmaster + </clix:lambda-list> + clix:returnsacceptor + </clix:returns> + clix:description +This is an accessor for the slot of a clix:refTASKMASTER</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:descriptionEscapes the characters #<, #>, #', #", and #& for HTML output. </clix:description> </clix:function> - <clix:function generic='true' name='execute-acceptor'> - clix:lambda-listtaskmaster - </clix:lambda-list> - clix:returnsresult - </clix:returns> - clix:descriptionThis 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-listname clix:lkwoptional @@ -1578,25 +1674,7 @@ TIME. </clix:description> </clix:function> - <clix:function generic='true' name='handle-incoming-connection'> - clix:lambda-listtaskmaster socket - </clix:lambda-list> - clix:returnsresult - </clix:returns> - clix:descriptionThis 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-listpath clix:lkwoptional @@ -1782,11 +1860,7 @@ clix:descriptionAdds appropriate headers to completely prevent caching on most browsers. </clix:description> </clix:function> - <clix:class name='one-thread-per-connection-taskmaster'> - clix:descriptionA 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-listname clix:lkwoptional @@ -2449,26 +2523,6 @@ (case-sensitive) already exists, it is replaced. </clix:description> </clix:function> - <clix:function generic='true' name='shutdown'> - clix:lambda-listtaskmaster - </clix:lambda-list> - clix:returnsresult - </clix:returns> - clix:descriptionShuts 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:descriptionA 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:descriptionAn 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-listtaskmaster - </clix:lambda-list> - clix:returnsresult - </clix:returns> - clix:description - </clix:description> - </clix:accessor> - <clix:accessor specialized='(TASKMASTER)' name='taskmaster-acceptor'> - clix:lambda-list(taskmaster taskmaster) - </clix:lambda-list> - clix:returnsresult - </clix:returns> - clix:description - </clix:description> - </clix:accessor> <clix:function name='url-decode'> clix:lambda-liststring clix:lkwoptional
-
BKNR Commits