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:refHANDLE-INCOMING-CONNECTION</clix:ref> is applied to - the taskmaster which will call - clix:refPROCESS-CONNECTION</clix:ref>. + the taskmaster which will either call + clix:refPROCESS-CONNECTION</clix:ref> directly, + or will create a thread to call it. 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 @@ -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:refTASKMASTER</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:refTASKMASTER</clix:ref> or one of its subclasses, + clix:refSINGLE-THREADED-TASKMASTER</clix:ref> or + clix:refONE-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: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. + + If the taskmaster is a multi-threaded taskmaster, clix:refHANDLE-INCOMING-THREAD</clix:ref> + will call clix:refCREATE-TASKMASTER-THREAD</clix:ref>, which will call + clix:refPROCESS-CONNECTION</clix:ref> in a new thread. + clix:refHANDLE-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-listtaskmaster socket + </clix:lambda-list> + clix:returnsthread + </clix:returns> + clix:descriptionThis function is called by clix:refHANDLE-INCOMING-THREAD</clix:ref> + to create a new thread which calls clix:refPROCESS-CONNECTION</clix:ref>. + If you specialize this function, you must be careful to have the thread + call clix:refDECREMENT-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>