--- /dev/null
+---
+postid: 000
+title: Hunchentoot: taskmaster code review
+date: August 16, 2019
+author: Lucian Mogoșanu
+tags: tech, tmsr
+---
+
+Hunchentoot taskmasters are, as the name suggests, an abstraction for
+work management, or in other words, they implement decision-making for
+work distribution among processing units. On the surface they look
+very similar to Apache's [MPM][apache-mpm] model, which (again, viewed
+very superficially) suggests Hunchentoot was lispers' attempt at an
+Apache reimplementation.
+
+As presented in the earlier [architectural overview][ht-iii],
+taskmasters expose the following methods: execute-acceptor,
+handle-incoming-connection and shutdown. In very broad lines,
+execute-acceptor gets called on [start][ht-s] and sets up an execution
+context where [accept-connections][ht-ac] is called;
+handle-incoming-connection is then called on each new connection and
+calls [process-connection][ht-pc]; and finally, shutdown is called by
+[stop][ht-pc], to suspend processing on all threads. Additionally,
+(specific) taskmasters may expose other methods[^1] that specific to
+their operation.
+
+The taskmaster class provides three subclasses: a single-threaded
+implementation, an abstract "multi-threaded" taskmaster and a concrete
+"one thread per connection" taskmaster -- otherwise the coad under
+examination is also structured to accommodate the usual
+[ifdefisms][ht-ifdefism], which we'll blissfully ignore. This being
+said, let us look at each taskmaster and the method it implements.
+
+<a name="s3" href="#s3">[s3]</a> [**shutdown**][ht-s3]: This is a
+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).
+
+<a name="stt-ea" href="#stt-ea">[stt-ea]</a>
+[**execute-acceptor**][ht-stt-ea]:
+
+<a name="stt-hic" href="#stt-hic">[stt-hic]</a>
+[**handle-incoming-connection**][ht-stt-hic]:
+
+Shutdown is provided by the [generic implementation](#s3) above.
+
+[**multi-threaded-taskmaster**][ht-mtt].
+
+It only provides an implementation for:
+
+<a name="mtt-ea" href="#mtt-ea">[mtt-ea]</a>
+[**execute-acceptor**][ht-mtt-ea]:
+
+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
+[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
+sent to the client.
+
+Below I'll detail (top-down) the implementation of
+handle-incoming-connection, shutdown and (the additional)
+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]:
+
+<a name="otpct-hic" href="#otpct-hic">[otpct-hic]</a>
+[**handle-incoming-connection**][ht-otpct-hic]:
+
+<a name="otpct-s3" href="#otpct-s3">[otpct-s3]</a>
+[**shutdown**][ht-otpct-s3]:
+
+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]:
+
+<a name="otpct-dtac" href="#otpct-dtac">[otpct-dtac]</a>
+[**decrement-taskmaster-accept-count**][ht-otpct-dtac]:
+
+<a name="otpct-ittc" href="#otpct-ittc">[otpct-ittc]</a>
+[**increment-taskmaster-thread-count**][ht-otpct-ittc]:
+
+<a name="otpct-dttc" href="#otpct-dttc">[otpct-dttc]</a>
+[**decrement-taskmaster-thread-count**][ht-otpct-dttc]:
+
+<a name="otpct-nfc" href="#otpct-nfc">[otpct-nfc]</a>
+[**note-free-connection**][ht-otpct-nfc]:
+
+<a name="otpct-wffc" href="#otpct-wffc">[otpct-wffc]</a>
+[**wait-for-free-connection**][ht-otpct-wffc]:
+
+<a name="otpct-tmtr" href="#otpct-tmtr">[otpct-tmtr]</a>
+[**too-many-taskmaster-requests**][ht-otpct-tmtr]:
+
+<a name="otpct-crht" href="#otpct-crht">[otpct-crht]</a>
+[**create-request-handler-thread**][ht-otpct-crht]:
+
+<a name="otpct-hic2" href="#otpct-hic2">[otpct-hic2]</a>
+[**handle-incoming-connection%**][ht-otpct-hic]:
+
+<a name="otpct-ssur" href="#otpct-ssur">[otpct-ssur]</a>
+[**send-service-unavailable-reply**][ht-otpct-ssur]:
+
+<a name="otpct-cas" href="#otpct-cas">[otpct-cas]</a>
+[**client-as-string**][ht-otpct-cas]:
+
+[^1]: Though all methods are piled together in the same place and,
+ say, default "thread count" implementations are provided for some
+ taskmasters that have nothing to do with multithreading. This is
+ a first sign that whoever wrote the code must have been fucked
+ in the head.
+
+[^2]: Which isn't to say there couldn't be more than one
+ multi-threaded-taskmaster implementation, we just haven't seen any
+ others. The very same, however, could be said about
+ e.g. shit. Sure, it could come from a human, a cow or a horse, but
+ for all intents and purposes it's still shit, so why the
+ additional layer of indirection?
+
+ Oh, it could be extended? Well, show me one of these
+ extensions. And if there are any, why aren't they in Hunchentoot?
+
+[apache-mpm]: https://httpd.apache.org/docs/2.2/en/mpm.html
+[ht-iii]: /posts/y06/097-hunchentoot-iii.html
+[ht-stt]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L127
+[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-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
+[ht-otpct-mac]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L198
+[ht-otpct-wq]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L222
+[ht-otpct-ii]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L272
+[ht-otpct-itac]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L281
+[ht-otpct-dtac]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L286
+[ht-otpct-ittc]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L291
+[ht-otpct-dttc]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L296
+[ht-otpct-nfc]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L306
+[ht-otpct-wffc]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L311
+[ht-otpct-tmtr]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L317
+[ht-otpct-crht]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L322
+[ht-s3]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L345
+[ht-otpct-s3]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L348
+[ht-otpct-hic]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L354
+[ht-otpct-hic2]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L359
+[ht-otpct-ssur]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L392
+[ht-otpct-cas]: http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L416
+[ht-s]: /posts/y06/098-hunchentoot-iv.html#s
+[ht-s2]: /posts/y06/098-hunchentoot-iv.html#s2
+[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
projects / thetarpit.git / commitdiff