[bknr-cvs] edi changed trunk/thirdparty/hunchentoot/doc/index.xml
BKNR Commits
bknr at bknr.net
Tue Feb 17 23:31:17 UTC 2009
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.
+<p>
+If you want to implement your own taskmasters, you should subclass
+<clix:ref>TASKMASTER</clix:ref> and specialize the generic functions in this section.
+</p>
+
+ <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.
+<p>
+This is the default taskmaster implementation for multi-threaded Lisp
+implementations.
+</p>
+ </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-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: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
More information about the Bknr-cvs
mailing list