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

[Stuart Marks]

On Wed, 3 Aug 2022 16:19:42 GMT, Alan Bateman <alanb 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 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".

Alex and I discussed this and we felt that it was important to call out all three "kinds" of threads explicitly. Earlier versions of the text implied that no non-daemon threads were running at the time the VM terminated, which might not be true. Earlier text also implied that shutdown hooks had terminated before the VM terminated, but this isn't necessarily true if somebody calls halt(). Yes, a shutdown hook has a daemon/non-daemon bit, but effectively it's ignored, and a shutdown hook is treated so specially that it's effectively a different kind of thread.

> 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.

I linked to the Thread.UncaughtExceptionHandler class, which details the whole process.

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

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