RFR: 8290036: adjustments to specification of Runtime::addShutdownHook

[Alan Bateman]

On Fri, 8 Jul 2022 23:00:15 GMT, Stuart Marks <smarks at openjdk.org> wrote:

> Initial edits to addShutdownHook from Alex.
> 
> See [JDK-8290036](https://bugs.openjdk.org/browse/JDK-8290036).

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

> 67:  * and
> 68:  * {@link #removeShutdownHook removeShutdownHook}
> 69:  * is prohibited. The shutdown hooks are then started in some unspecified order,

Are you planning to "reflow" to get the line lengths a bit more consistent? Only asking because some places after line breaks after 40-50 characters, a few others stray out beyond 100 characters.

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

> 69:  * is prohibited. The shutdown hooks are then started in some unspecified order,
> 70:  * and they are allowed to run concurrently. Any already-existing threads and any
> 71:  * newly started threads also continue to run concurrently during the shutdown sequence.

Instead of "Any already-existing threads" then you could say "Existing {@linkplain Thread#isAlive() live} threads".

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

> 76:  * In this case other threads (including shutdown hooks) continue to execute and can
> 77:  * terminate the JVM via the {@link #halt halt} method.
> 78:  * <h2><a id="termination">Virtual Machine Termination</a></h2>

You might want to insert a line break at the end of the "Shutdown Sequence" section so that it doesn't run into the "Virtual Machine Termination" section.

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

> 77:  * terminate the JVM via the {@link #halt halt} method.
> 78:  * <h2><a id="termination">Virtual Machine Termination</a></h2>
> 79:  * When the JVM terminates, all threads (daemon, non-daemon, and shutdown hooks) are immediately

"daemon, non-daemon, and shutdown hooks" reads like there are 3 kinds of threads. I would be tempted to drop "shutdown hooks" from this list or else phrase it as "all shutdown hooks and all other threads".

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

> 172:      * Uncaught exceptions are handled in shutdown hooks just as in any other thread,
> 173:      * by invoking the {@link ThreadGroup#uncaughtException uncaughtException}
> 174:      * method of the thread's {@link ThreadGroup} object. After the uncaught exception

Uncaught exception handling is a bit more complicated as there can be per-thread and default UHE set. I think it would be better to not mention ThreadGroup and instead just link to Thread#setDefaultUncaughtExceptionHandler.

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

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