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

[David Holmes]

On Thu, 11 Aug 2022 04:00:39 GMT, Stuart Marks <smarks at openjdk.org> wrote:

>> The concept of the shutdown sequence needs to be specified more clearly. This PR adds text for this into the class specification of `java.lang.Runtime`. Also includes adjustments to related areas in `addShutdownHook`, `halt`, and in the `System` and `Thread` classes. The changes here should coordinate with similar changes to JLS 12.8, JVMS 5.7, and the Invocation API chapter of the _JNI Specification._
>
> Stuart Marks has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Revise Implementation Note discussing JNI Invocation API.

src/java.base/share/classes/java/lang/Runtime.java line 99:

> 97:  * <a href="{@docRoot}/../specs/jni/invocation.html">JNI Invocation API</a>
> 98:  * to control launching and termination of the JVM. Such native code invokes the
> 99:  * <a href="{@docRoot}/../specs/jni/invocation.html#jni_createjavavm">{@code JNI_CreateJavaVM}</a>

JNI {@code CreateJavaVM}

src/java.base/share/classes/java/lang/Runtime.java line 101:

> 99:  * <a href="{@docRoot}/../specs/jni/invocation.html#jni_createjavavm">{@code JNI_CreateJavaVM}</a>
> 100:  * function to launch the JVM. Subsequently, the native code invokes the
> 101:  * <a href="{@docRoot}/../specs/jni/invocation.html#destroyjavavm">{@code DestroyJavaVM}</a>

JNI {@code DestroyJavaVM}

to be consistent; or drop JNI from both.

src/java.base/share/classes/java/lang/Runtime.java line 103:

> 101:  * <a href="{@docRoot}/../specs/jni/invocation.html#destroyjavavm">{@code DestroyJavaVM}</a>
> 102:  * function to await termination of that JVM. The {@code DestroyJavaVM} function is responsible for
> 103:  * initiating the shutdown sequence when the number of {@linkplain Thread#isAlive() running}

s/running/live

"live" is consistent with Thread terminology

src/java.base/share/classes/java/lang/Runtime.java line 107:

> 105:  * terminates, control is returned to the native code that invoked {@code DestroyJavaVM}.
> 106:  * <p>
> 107:  * This differs from the {@link #exit exit} or {@link #halt halt} methods. These methods typically

In a new paragraph it is not clear what "This" refers to. I would run this into the previous paragraph as:

> This behavior differs from the {@link #exit exit} or {@link #halt halt} methods, which typically terminate the OS process hosting the JVM and do not interact with the JNI Invocation API.

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

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