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

[Alan Bateman]

On Sat, 6 Aug 2022 00:42:23 GMT, Stuart Marks <smarks at openjdk.org> wrote:

>> Initial edits to addShutdownHook from Alex.
>> 
>> See [JDK-8290036](https://bugs.openjdk.org/browse/JDK-8290036).
>
> Stuart Marks has updated the pull request incrementally with one additional commit since the last revision:
> 
>   More edits from Alex's suggestions.

src/java.base/share/classes/java/lang/System.java line 1888:

> 1886:      * Initiates the <a href="Runtime.html#shutdown">shutdown sequence</a> of the Java Virtual
> 1887:      * Machine. This method always blocks indefinitely. The
> 1888:      * argument serves as a status code; by convention, a nonzero status

Would you remind reflowing this one too as the latest change makes mixes the line lengths again.

src/java.base/share/classes/java/lang/Thread.java line 73:

> 71:  * or if its {@code run} method completes abruptly and the appropriate
> 72:  * {@linkplain Thread.UncaughtExceptionHandler uncaught exception handler} completes
> 73:  * normally or abruptly. With no code left to run, the thread has completed execution.

I'm in two minds about introducing the UHE in paragraph 3 but probably okay as you kinda have to mention it when defining termination. There's a lot more to this story when you have agents in the picture but I'll not go there. I wonder if we can do something with the last sentence that includes the word "terminated". We use "terminated" in several places and it would be cleared if this sentence were to end with something like "... the thread has completes execution, and is terminated" (it could link to isAlive or Thread.State#TERMINATED).

Given that the join method is introduced as the method to wait for a thread to terminate then it could be part of this paragraph rather than a single sentence paragraph.

src/java.base/share/classes/java/lang/Thread.java line 104:

> 102:  * The <a href="Runtime.html#shutdown">shutdown sequence</a> begins when all started
> 103:  * non-daemon threads have terminated. Unstarted non-daemon threads do not prevent
> 104:  * the shutdown sequence from commencing. Invoking the {@linkplain Runtime#exit(int)}

I think this is the only usage of "commencing", everywhere else uses "beginning" or "begin the shutdown sequence".

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

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