RFR: 8295857: Clarify that cleanup code can be skipped when the JVM terminates (e.g. when calling halt()) [v4]

[Stuart Marks]

On Tue, 22 Nov 2022 22:24:00 GMT, David Holmes <dholmes at openjdk.org> wrote:

>> Brent Christian has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Update Runtime class doc re: other unexpected behaviors
>
> src/java.base/share/classes/java/lang/Runtime.java line 97:
> 
>> 95:  * no {@code finally} clause of any method is executed, and try-with-resources
>> 96:  * blocks do not {@linkplain AutoCloseable close} their resources.
>> 97:  * Other unexpected behaviors may also result.
> 
> No sorry that doesn't work for me. It sounds like you might get unexpected things happening, when in fact it is things not happening that might surprise someone (who doesn't understand what "immediately prevented from executing any further Java code" means). The list of examples is getting too long to handle in sentence structure so I suggest an actual list (not sure of list syntax). Suggestion:
> 
> 
>  * Java code. This includes shutdown hooks as well as daemon and non-daemon threads. This 
>  * means, for example, that:
>  * - threads' current methods do not complete normally or abruptly
>  *  - no {@code finally} clause of any method is executed
>  *  - no {@linkplain Thread.UncaughtExceptionHandler uncaught exception handler} is executed
>  *  - no try-with-resources blocks {@linkplain AutoCloseable close} their resources

I think it's reasonable to position these as examples and to put them into list form.

(wordsmithing) For parallel structure I'd suggest "X does not occur" instead of "no X occurs" in all but the first item, specifically (markup elided):

 - threads' current methods do not complete normally or abruptly;
 - finally clauses are not executed;
 - uncaught exception handlers are not executed; and
 - resources opened by try-with-resources statements are not closed.

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

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