drafts, hunchentoot-v: Update

diff --git a/drafts/000-hunchentoot-v.markdown b/drafts/000-hunchentoot-v.markdown
index b9453cd..39e2d5d 100644 (file)
--- a/drafts/000-hunchentoot-v.markdown
+++ b/drafts/000-hunchentoot-v.markdown
@@ -36,35 +36,38 @@ generic implementation, that can be (and is, in one case, as shown
 below) overriden by subclasses; this implementation doesn't do
 anything except returning the taskmaster object.
 
-[**single-threaded-taskmaster**][ht-stt].
-
-The simplest taskmaster implementation; probably not very useful for
-battlefield use (TODO: add link to discussion on this).
+[**single-threaded-taskmaster**][ht-stt]: The simplest taskmaster
+implementation; probably not very useful for battlefield use, because
+of poor load handling, [blocking operations][tlogz-1926874] and so on.
 
 <a name="stt-ea" href="#stt-ea">[stt-ea]</a>
-[**execute-acceptor**][ht-stt-ea]:
+[**execute-acceptor**][ht-stt-ea]: Calls [accept-connections][ht-ac].
 
 <a name="stt-hic" href="#stt-hic">[stt-hic]</a>
-[**handle-incoming-connection**][ht-stt-hic]:
+[**handle-incoming-connection**][ht-stt-hic]: Calls
+[process-connection][ht-pc].
 
 Shutdown is provided by the [generic implementation](#s3) above.
 
-[**multi-threaded-taskmaster**][ht-mtt].
-
-It only provides an implementation for:
+[**multi-threaded-taskmaster**][ht-mtt]: Defines a new
+[acceptor-process][ht-mtt-ap] field denoting a new thread whose sole
+work is accepting new connections. Thus, this acceptor only provides
+an implementation for:
 
 <a name="mtt-ea" href="#mtt-ea">[mtt-ea]</a>
-[**execute-acceptor**][ht-mtt-ea]:
+[**execute-acceptor**][ht-mtt-ea]: Starts a new "listener" thread
+which waits for new connections; essentially the same as [the
+single-threaded version](#ht-stt-ea), only accept-connections runs on
+a separate thread.
 
 All the other methods are implemented by
 sub-multi-threaded-taskmasters, i.e. by
 one-thread-per-connection-taskmaster[^2].
 
-[**one-thread-per-connection-taskmaster**][ht-otpct].
-
-As the name suggests, each new connection will spawn a new thread when
-it is to be handled. Up to [max-thread-count][ht-otpct-mtc]
-connections are accepted, and then the remaining connections up to
+[**one-thread-per-connection-taskmaster**][ht-otpct]: As the name
+suggests, each new connection will spawn a new thread when it is to be
+handled. Up to [max-thread-count][ht-otpct-mtc] connections are
+accepted, and then the remaining connections up to
 [max-accept-count][ht-otpct-mac] are [queued][ht-otpct-wq] waiting for
 a thread to be allocated for them. If both counts are exceeded (or if
 the former is exceeded and the latter is not set) then a HTTP 503 is
@@ -76,7 +79,14 @@ initialize-instance -- the execute-acceptor executed is that of the
 [superclass](#mtt-ea).
 
 <a name="otpct-ii" href="#otpct-hic">[otpct-ii]</a>
-[**initialize-instance**][ht-otpct-ii]:
+[**initialize-instance**][ht-otpct-ii]: This is an ":after" method
+which, given a new taskmaster instance, does some sanity checking,
+i.e. that: a. if max-accept-count is supplied, then so is
+max-thread-count, and b. that the former is higher than the
+latter. The idea here is that the number of Hunchentoot worker threads
+is either unlimited, or limited by max-thread-count -- in the former
+case, max-accept-count doesn't really make sense, because all new
+connections are accepted.
 
 <a name="otpct-hic" href="#otpct-hic">[otpct-hic]</a>
 [**handle-incoming-connection**][ht-otpct-hic]:
@@ -88,16 +98,23 @@ As observed, these methods are implemented using the following
 "support" methods and functions:
 
 <a name="otpct-itac" href="#otpct-itac">[otpct-itac]</a>
-[**increment-taskmaster-accept-count**][ht-otpct-itac]:
+[**increment-taskmaster-accept-count**][ht-otpct-itac]: Atomically
+increments the accept-count at a given time.
 
 <a name="otpct-dtac" href="#otpct-dtac">[otpct-dtac]</a>
-[**decrement-taskmaster-accept-count**][ht-otpct-dtac]:
+[**decrement-taskmaster-accept-count**][ht-otpct-dtac]: Atomically
+decrements the accept-count at a given time.
 
 <a name="otpct-ittc" href="#otpct-ittc">[otpct-ittc]</a>
-[**increment-taskmaster-thread-count**][ht-otpct-ittc]:
+[**increment-taskmaster-thread-count**][ht-otpct-ittc]: Atomically
+increments the thread-count at a given time.
 
 <a name="otpct-dttc" href="#otpct-dttc">[otpct-dttc]</a>
-[**decrement-taskmaster-thread-count**][ht-otpct-dttc]:
+[**decrement-taskmaster-thread-count**][ht-otpct-dttc]: Atomically
+decrements the thread-count at a given time; when thread-count falls
+under max-accept-count, notifies listener via
+[note-free-connection](#otpct-nfc) that new connections may be
+handled.
 
 <a name="otpct-nfc" href="#otpct-nfc">[otpct-nfc]</a>
 [**note-free-connection**][ht-otpct-nfc]:
@@ -142,6 +159,7 @@ As observed, these methods are implemented using the following
 [ht-stt-ea]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L137
 [ht-stt-hic]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L141
 [ht-mtt]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L149
+[ht-mtt-ap]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L150
 [ht-mtt-ea]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L158
 [ht-otpct]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L175
 [ht-otpct-mtc]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L177
@@ -167,3 +185,4 @@ As observed, these methods are implemented using the following
 [ht-ac]: /posts/y06/098-hunchentoot-iv.html#ac
 [ht-pc]: /posts/y06/098-hunchentoot-iv.html#pc
 [ht-ifdefism]: /posts/y06/098-hunchentoot-iv.html#selection-195.296-199.206
+[tlogz-1926874]: http://logs.nosuchlabs.com/log/trilema/2019-08-09#1926874