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

[David Holmes]

On Thu, 19 Dec 2024 04:48:52 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

>> Please review this simple clarification to the Java command reference / manpage.
>> 
>> Thanks
>
> Hello David, for end users, the distinction between a JVM vs some code running within the Java runtime may not be too clear or obvious. So I think even with this added clarification there might be situations where people will be surprised and will report that these options aren't doing the actions that they expect when OutOfMemoryError is thrown.
> But this change is still an improvement to what we currently have. So this looks good to me.
> 
> While at it, I noticed in a related JBS issue https://bugs.openjdk.org/browse/JDK-8257790 that you mentioned two additional options `ExitOnOutOfMemory` and `CrashOnOutOfMemoryError`. Those don't seem to be documented in this man page. Are those still relevant and should they be documented too (as a separate issue)?

Thanks for taking a look at this @jaikiran .

> you mentioned two additional options ExitOnOutOfMemory and CrashOnOutOfMemoryError. Those don't seem to be documented in this man page.

The majority of -XX flags are not documented, and intentionally so. It is somewhat of a legacy situation, whereby -XX flags that tended to be "heavily used" by end users (or were perceived to be potentially useful for end users) were documented. Primarily GC and JIT tuning flags, but also others related to serviceability and debugging. Documenting them can be seen as an encouragement to use them, when that is not the intent for end-users.

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

PR Comment: https://git.openjdk.org/jdk/pull/22802#issuecomment-2552987648