[bknr-cvs] edi changed trunk/thirdparty/hunchentoot/doc/index.xml
BKNR Commits
bknr at bknr.net
Tue Feb 17 22:59:48 UTC 2009
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>.
+
+<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-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 <em>must</em> 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 <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-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>
More information about the Bknr-cvs
mailing list