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

[Thomas Stuefe]

On Thu, 19 Dec 2024 07:47:23 GMT, David Holmes <dholmes at openjdk.org> wrote:

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

We don't need a 100% text. Mentioning self-thrown OOMEs and Thread creation OOMs as exceptions should cover almost all cases I know of where customers were puzzled.

"This applies only to Out-Of-Memory errors caused by Java Heap exhaustion; it does not apply to OOMEs thrown by user code, nor OOMEs caused by other types of resource exhaustion (e.g. thread creation errors)."

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

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