RFR: 8346477: Clarify the Java manpage in relation to the JVM's OnOutOfMemoryError flags

[David Holmes]

On Thu, 19 Dec 2024 07:43:11 GMT, Thomas Stuefe <stuefe at openjdk.org> wrote:

>> Please review this simple clarification to the Java command reference / manpage.
>> 
>> Thanks
>
> src/java.base/share/man/java.md line 1301:
> 
>> 1299:     option.
>> 1300:     This does not apply to any `OutOfMemoryError` thrown by Java, or native,
>> 1301:     code in the JDK libraries.
> 
>> This does not apply to any `OutOfMemoryError` thrown by Java, or native, code in the JDK libraries.
> 
> This is vague. Does not apply to OOMEs raised explicitly via throw? Or only if thrown from Java code in JDK libraries? So, user code throws are fine? Or, does not apply for OOMEs thrown by JDK libraries regardless of Java or Native? But then, how would a customer know where an exception is thrown without knowing the sources for JDK libraries and hotspot JVM? Why would the throw point even matter?
> 
> In my experience, whether or not the OnOOM handling kicks in is a mystery to many customers. We should clearly list the typical points where OnOOM does not work but one would expect it to work, e.g. thread creation errors and explicit throws, regardless of where the throw happens.

Thanks for taking a look @tstuefe. I realize it is not at all obvious when exceptions originate from the VM, but the intent was to make it clear(er) (and I seem to have failed :) ) that if you ever see `throw new OutOfMemoryError()` then that is definitely NOT one that comes from the VM.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/22802#discussion_r1891292536