RFR: JDK-8002152: javadoc could write out files on a worker thread

[Jonathan Gibbons]

On Mon, 22 Feb 2021 17:56:25 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Here's some more thoughts. I tweaked this change to see when the thread that submits tasks cannot immediately acquire a permit. Using that tweaked change I built documentation for JDK for various number of queued tasks (QUEUED_TASKS). That allowed me to collect the following statistics:
>> 
>> 
>> | queue, n | attempts, n | failed, n | utilization, % |
>> | -------- | ----------- | --------- | -------------- |
>> |        0 |       14789 |      3346 |             19 |
>> |        5 |           " |       348 |             20 |
>> |       10 |           " |       120 |             20 |
>> |       15 |           " |        30 |             20 |
>> |       20 |           " |	  10 |             19 |
>> |      100 |           " |         0 |             19 |
>> 
>> 1. Either I'm misinterpreting these results or the original premises (1) "we currently consume (execute) tasks faster than we produce them" and (2) "A semaphore is used to throttle the number of requests, although in practice this rarely takes effect, because it is quicker to write documents than to generate them" do not hold on my machine. In particular, when QUEUED_TASKS == 0, the task-submitting thread fails to immediately acquire a permit in a quarter of attempts.
>> 2. Note that "utilization" doesn't change even though the `ExecutorService` always has tasks to execute. That raises a question of how to interpret "utilization".
>
> Thanks for the detailed comments.
> 
> As regards your experiments for different queue sizes, it would be interesting to monitor the average size of the queue, to help pick a reasonable value.  But that being said, there is very little change in the utilization of the background writer as a function of the question size, which suggests it's not not important to raise the value ... and higher values may lead to higher memory usage.
> 
> Instead of increasing the queue size, it might be interesting to repeat the experiments to increase the number of threads.

Over the weekend, I tried a few times to move option deciding into `BackgroundWriter`. In the end I decided it is not worth it for just the two values currently supported.  But, we could extend the option decoding to allow the number of threads and queue size to be specified, in which case I would add a static nested `Options` class into `BackgroundWriter` and delegate to that from `HtmlOptions`.

But equally, while these experiments are fun, I'm n to sure there's much more to be gained once we decide on some initial default values.

-------------

PR: https://git.openjdk.java.net/jdk/pull/2665