RFR: 8290036: Define and specify Runtime shutdown sequence [v4]

[Alan Bateman]

On Tue, 9 Aug 2022 05:51:17 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> The whole paragraph is about thread termination, so I don't think we need to say "terminate" again in the last sentence. We could mention isAlive or the TERMINATED state, but that brings in Thread.State which which require a discussion of the thread's life cycle.
>> 
>> The "join" sentence was kind of tacked on to the end of a paragraph in the original text; Alex suggested that I separate it into its own paragraph when we were working on the "termination" paragraph. Alex doesn't mind single-sentence paragraphs, which isn't my preference. But tacking the "join" sentence onto the end of the "termination" paragraph actually doesn't make any sense. Termination is something that happens to _this_ thread. The join method is called from _another_ thread, and this implicit shift of viewpoint would weaken the paragraph.
>> 
>> Frankly I think there needs to be a separate editorial pass over the Thread docs. I know they were just rewritten in JDK 19, but there are some odd things about it. The Thread.State life cycle isn't explained and isn't referenced by methods such as start() and isAlive(). Also, various mentions of uncaught exception handling talk about a thread's abrupt termination. There isn't any such thing; a _method_ can complete normally or abruptly, and when a thread's run() method completes either way, the thread simply terminates.
>
> Thread.State was added (in Java 5) for monitoring and management purposes, it's not an API that most libraries or programs would use. It could be introduced in the class description and referenced from other APIs that change/test the state but it would encourage use beyond the original intent.

What you have is okay although I would have preferred if the sentence on the join method was in the previous paragraph rather as it fits with termination.

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

PR: https://git.openjdk.org/jdk/pull/9437