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:refACCEPTOR</clix:ref> +(or clix:refSSL-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:refSTART</clix:ref> which +immediately calls clix:refSTART-LISTENING</clix:ref> and then applies the function +clix:refEXECUTE-ACCEPTOR</clix:ref> to +its <a href="#taskmasters">taskmaster</a>. This function will +eventually call clix:refACCEPT-CONNECTIONS</clix:ref> which is +responsible for settings things up to wait for clients to connect. +For each connection which comes +in, clix:refHANDLE-INCOMING-CONNECTION</clix:ref> is applied to the +taskmaster which will call clix:refPROCESS-CONNECTION</clix:ref>. +clix:refPROCESS-CONNECTION</clix:ref> +calls clix:refINITIALIZE-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:refRESET-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:refSTOP</clix:ref>. + +<p> +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. +</p> + + <clix:function generic='true' name='start-listening'> + clix:lambda-listacceptor + </clix:lambda-list> + clix:returns| + </clix:returns> + clix:descriptionSets 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-listacceptor + </clix:lambda-list> + clix:returnsnil + </clix:returns> + clix:descriptionIn a loop, accepts a connection and hands it over +to the acceptor's taskmaster for processing using +clix:refHANDLE-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-listacceptor socket + </clix:lambda-list> + clix:returnsnil + </clix:returns> + clix:descriptionThis function is called by the taskmaster when a +new client connection has been established. Its arguments are the +clix:refACCEPTOR</clix:ref> object and a LispWorks socket handle or a usocket socket +stream object in clix:argsocket</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-listacceptor stream + </clix:lambda-list> + clix:returnsstream + </clix:returns> + clix:descriptionCan 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:refACCEPTOR</clix:ref> does nothing, but +see for example the method defined +for clix:refSSL-ACCEPTOR</clix:ref>. All methods of this generic +function <em>must</em> return the stream to use. + </clix:description> + </clix:function> + + <clix:function generic='true' name='reset-connection-stream'> + clix:lambda-listacceptor stream + </clix:lambda-list> + clix:returnsstream + </clix:returns> + clix:descriptionResets 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 <em>must</em> 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-listacceptor stream - </clix:lambda-list> - clix:returnsresult - </clix:returns> - clix:descriptionCan 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-listlog-level format-string clix:lkwrest @@ -1752,20 +1846,7 @@ object REQUEST. </clix:description> </clix:function> - <clix:function generic='true' name='process-connection'> - clix:lambda-listacceptor socket - </clix:lambda-list> - clix:returnsresult - </clix:returns> - clix:descriptionThis 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:lkwoptional @@ -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-listacceptor stream - </clix:lambda-list> - clix:returnsresult - </clix:returns> - clix:descriptionResets 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-listacceptor - </clix:lambda-list> - clix:returnsresult - </clix:returns> - clix:descriptionSets 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>