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

[Jonathan Gibbons]

On Mon, 22 Feb 2021 11:48:10 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> The standard doclet works by creating `HtmlDocument` objects and then writing them out. Writing them can be safely done on a separate thread, and doing so results in about an 8% speedup, by overlapping the write/IO time with the time to generate the next page to be written.
>> 
>> The overall impact on the codebase is deliberately small, coming down to a critical `if` statement in `HtmlDocletWriter` to "write now" or "write later". As such, it is easy to disable the feature if necessary, although no issues have been found in practice. The background writer uses an `ExecutorService`, which provides a lot of flexibility, but experiments show that it is sufficient to use a single background thread and to block if new tasks come available while writing a file.
>> 
>> The feature is "default on", with a hidden option to disable it if necessary.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/BackgroundWriter.java line 2:
> 
>> 1: /*
>> 2:  * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
> 
> Is this just an outdated copyright header or this class is really that old?

Yes, the code really is that old.  At the time, we were disappointed that the speedup was not bigger (!) and that we could not easily make more of the generation be concurrent. But, given that the footprint of this fix on the code is low, and that we are elsewhere fixing perf regressions of under 5%, I think it is worth incorporating this code.

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

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