[bknr-cvs] hans changed trunk/thirdparty/hunchentoot/doc/index.xml
BKNR Commits
bknr at bknr.net
Wed Mar 9 18:15:45 UTC 2011
Revision: 4659
Author: hans
URL: http://bknr.net/trac/changeset/4659
documentation update from Scott McKay and Dan Weinreb to document the
resource usage limitation changes.
U trunk/thirdparty/hunchentoot/doc/index.xml
Modified: trunk/thirdparty/hunchentoot/doc/index.xml
===================================================================
--- trunk/thirdparty/hunchentoot/doc/index.xml 2011-03-03 07:21:56 UTC (rev 4658)
+++ trunk/thirdparty/hunchentoot/doc/index.xml 2011-03-09 18:15:44 UTC (rev 4659)
@@ -214,7 +214,7 @@
<clix:chapter name="start" title="Your own webserver (the easy teen-age New York version)">
Starting your own web server is pretty easy. Do something like this:
-<pre>(hunchentoot:<a class="noborder" href="#start">start</a> (make-instance 'hunchentoot:<a class="noborder" href="#acceptor">acceptor</a> :port 4242))</pre>
+<pre>(hunchentoot:<a class="noborder" href="#start">start</a> (make-instance 'hunchentoot:<a class="noborder" href="#acceptor">easy-acceptor</a> :port 4242))</pre>
That's it. Now you should be able to enter the address
"<a href='http://127.0.0.1:4242/'><code>http://127.0.0.1:4242/</code></a>" in
your browser and see something, albeit nothing very interesting
@@ -591,8 +591,9 @@
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>.
+ the taskmaster which will either call
+ <clix:ref>PROCESS-CONNECTION</clix:ref> directly,
+ or will create a thread to call it.
<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
@@ -756,11 +757,48 @@
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.
+ You can control the resources consumed by a threaded taskmaster via
+ two initargs. <code>:max-thread-count</code> lets you set the maximum
+ number of request threads that can be processes simultaneously. If
+ this is <code>nil</code>, the is no thread limit imposed.
+
+ <code>:max-accept-count</code> lets you set the maximum number of requests
+ that can be outstanding (i.e. being processed or queued for processing).
+
+ If <code>:max-thread-count</code> is supplied and <code>:max-accept-count</code>
+ is <code>NIL</code>, then a <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>
+ error will be generated if there are more than the max-thread-count
+ threads processing requests. If both <code>:max-thread-count</code>
+ and <code>:max-accept-count</code> are supplied, then max-thread-count
+ must be less than max-accept-count; if more than max-thread-count
+ requests are being processed, then requests up to max-accept-count
+ will be queued until a thread becomes available. If more than
+ max-accept-count requests are outstanding, then a <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>
+ error will be generated.
+
+ In a load-balanced environment with multiple Hunchentoot servers, it's
+ reasonable to provide <code>:max-thread-count</code> but leave
+ <code>:max-accept-count</code> null. This will immediately result
+ in <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref> when one server is
+ out of resources, so the load balancer can try to find another server.
+
+ In an environment with a single Hunchentoot server, it's reasonable
+ to provide both <code>:max-thread-count</code> and a somewhat larger value
+ for <code>:max-accept-count</code>. This will cause a server that's almost
+ out of resources to wait a bit; if the server is completely out of resources,
+ then the reply will be <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>.
+ The default for these values is 100 and 120, respectively.
</p>
+
+ <p>
+ If you want to implement your own taskmasters, you should subclass
+ <clix:ref>TASKMASTER</clix:ref> or one of its subclasses,
+ <clix:ref>SINGLE-THREADED-TASKMASTER</clix:ref> or
+ <clix:ref>ONE-THREAD-PER-CONNECTION-TASKMASTER</clix:ref>, and
+ specialize the generic functions in this section.
+ </p>
<clix:class name='taskmaster'>
<clix:description>
@@ -822,6 +860,43 @@
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.
+
+ If the taskmaster is a multi-threaded taskmaster, <clix:ref>HANDLE-INCOMING-THREAD</clix:ref>
+ will call <clix:ref>CREATE-TASKMASTER-THREAD</clix:ref>, which will call
+ <clix:ref>PROCESS-CONNECTION</clix:ref> in a new thread.
+ <clix:ref>HANDLE-INCOMING-THREAD</clix:ref> might issue a
+ <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref> error
+ if there are too many request threads or it might block waiting for a
+ request thread to finish.
+ </clix:description>
+ </clix:function>
+
+ <clix:function generic='true' name='create-taskmaster-thread'>
+ <clix:lambda-list>taskmaster socket
+ </clix:lambda-list>
+ <clix:returns>thread
+ </clix:returns>
+ <clix:description>This function is called by <clix:ref>HANDLE-INCOMING-THREAD</clix:ref>
+ to create a new thread which calls <clix:ref>PROCESS-CONNECTION</clix:ref>.
+ If you specialize this function, you must be careful to have the thread
+ call <clix:ref>DECREMENT-TASKMASTER-REQUEST-COUNT</clix:ref> before
+ it exits. A typical method will look like this:
+
+ <pre>(defmethod create-taskmaster-thread ((taskmaster monitor-taskmaster) socket)
+ (bt:make-thread
+ (lambda ()
+ (with-monitor-error-handlers
+ (unwind-protect
+ (with-monitor-variable-bindings
+ (process-connection (taskmaster-acceptor taskmaster) socket))
+ (decrement-taskmaster-request-count taskmaster))))))</pre>
+
+
+
+
+
+
+
</clix:description>
</clix:function>
More information about the Bknr-cvs
mailing list