Summary

Simplify and clarify the behaviour of the reentrancy contract for Runtime::exit, so as to make it simpler and more straightforward to understand (and implement).

Problem

Earlier versions of the platform allowed for a small window between running the shutdown hooks and calling halt, where another thread could slip in its own call to exit. This was to facilitate Runtime::runFinalizersOnExit, which has since been removed (see JDK-8198249). Following on from that, it is now possible to revisit the reentrancy contract of Runtime::exit, so as to make it more straightforward and simpler to understand (and implement).

Solution

Update the specification of Runtime::exit to:

1. Remove the esoteric sentence that allows for a small window between running the shutdown hooks and calling halt.

2. Clarify the behaviour of subsequent invocations, specifically the fact that only one invocation can proceed with the shutdown sequence and terminate the VM with the given status code.

3. Clarify the danger of invocations from shutdown hooks that can lead to a deadlock.

Specification

Amend the following paragraph of java.lang.Runtime::exit:

   ...
-  * <p> If this method is invoked after all shutdown hooks have already
-  * been run and the status is nonzero then this method halts the
-  * virtual machine with the given status code. Otherwise, this method
-  * blocks indefinitely.
+  * <p> Invocations of this method are serialized such that only one
+  * invocation will actually proceed with the shutdown sequence and
+  * terminate the VM with the given status code. All other invocations
+  * will block indefinitely. If this method is invoked from a shutdown
+  * hook the system will deadlock.
   ...
   public void exit(int status) { ... }