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

[Pavel Rappo]

On Mon, 22 Feb 2021 13:03:04 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.
>
> This change is on the right track.
> 
> 1. Although I'm not sure how "utilization" translates to a similar measurement obtained through a profiling tool, I do think we can use "utilization" as a rough estimate.
> 
> FWIW, on my machine the base "utilization" for JDK codebase is 13%. After I have moved the initialization of the `start` timestamp from the creation of the writer closer to the submission of the first task, "utilization" increased to 17%.
> 
> I'd recommend computing elapsed times using `java.lang.System.nanoTime`. Using `nanoTime` avoids some hazards of using `currentTimeMillis` for such purposes.
> 
> 2. The `--background-writer` option is processed **after** the writer has been created. To see the "utilization" numbers I had to tweak the change and rebuild the project.

To add to my earlier comment https://github.com/openjdk/jdk/pull/2665#discussion_r580185985.

I reread the `ExecutorService` API to refresh my memory. It looks like there is **NO** happens-before edge between "actions taken by a task" and "awaitTermination returned true" . So, to read that `taskBusy` value safely we have to do something else.

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

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