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

[Thomas Stuefe]

On Wed, 18 Dec 2024 02:17:45 GMT, David Holmes <dholmes 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.

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

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