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

[dholmes-ora]

Please review this simple clarification to the Java command reference / manpage.

Thanks

---

Progress

• Change must be properly reviewed (1 review required, with at least 1 Reviewer)
• Change must not contain extraneous whitespace
• Commit message must refer to an issue

Issue

• JDK-8346477: Clarify the Java manpage in relation to the JVM's OnOutOfMemoryError flags (Enhancement - P4)

Reviewers

• Jaikiran Pai (@jaikiran - Reviewer)
• Thomas Stuefe (@tstuefe - Reviewer)

Contributors

• Thomas Stuefe <stuefe@openjdk.org>

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/22802/head:pull/22802
$ git checkout pull/22802

Update a local copy of the PR:
$ git checkout pull/22802
$ git pull https://git.openjdk.org/jdk.git pull/22802/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 22802

View PR using the GUI difftool:
$ git pr show -t 22802

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/22802.diff

Using Webrev

Link to Webrev Comment

[dholmes-ora]

/label add hotspot-runtime

[bridgekeeper]

👋 Welcome back dholmes! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

@dholmes-ora This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

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

Co-authored-by: Thomas Stuefe <stuefe@openjdk.org>
Reviewed-by: jpai, stuefe

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 98 new commits pushed to the master branch:

• c1b868d: 8346602: Remove unused macro parameters in jni.cpp
• 43b7e9f: 8346713: [testsuite] NeverActAsServerClassMachine breaks TestPLABAdaptToMinTLABSize.java TestPinnedHumongousFragmentation.java TestPinnedObjectContents.java
• 249f141: 8346737: GenShen: Generational memory pools should not report zero for maximum capacity
• d562d3c: 8343882: BasicAnnoTests doesn't handle multiple annotations at the same position
• 7ba969a: 8346739: jpackage tests failed after JDK-8345259
• b8e40b9: 8346688: GenShen: Missing metadata trigger log message
• d2a4863: 8346690: Shenandoah: Fix log message for end of GC usage report
• bcb1bda: 8345259: Disallow ALL-MODULE-PATH without explicit --module-path
• 054c644: 8346667: Doccheck: warning about missing before

• 2a68f74: 8346128: Comparison build fails due to difference in LabelTarget.html
• ... and 88 more: https://git.openjdk.org/jdk/compare/db9eab3f29e9cb26a8c0a7c31c55aaf140f21bed...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

[openjdk]

@dholmes-ora
The hotspot-runtime label was successfully added.

[mlbridge]

Webrevs

• 02: Full - Incremental (9a964173)
• 01: Full - Incremental (3c124837)
• 00: Full (f6af2e83)

[jaikiran]

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)?

[dholmes-ora]

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.

[dholmes-ora]

/contributor add @tstuefe

[openjdk]

@dholmes-ora
Contributor Thomas Stuefe <stuefe@openjdk.org> successfully added.

[tstuefe]

Thank you for considering my arguments. Looks good and trivial.

[jaikiran]

The majority of -XX flags are not documented, and intentionally so. ... Documenting them can be seen as an encouragement to use them, when that is not the intent for end-users.

Thank you for that detail.

[tstuefe]

Still good

[jaikiran]

The latest update looks good to me.

[dholmes-ora]

/integrate

[dholmes-ora]

Thanks for the reviews and suggestions.

[openjdk]

Going to push as commit cd15ebb.
Since your change was applied there have been 99 commits pushed to the master branch:

• bffa77b: 8346714: [ASAN] compressedKlass.cpp reported applying non-zero offset to null pointer
• c1b868d: 8346602: Remove unused macro parameters in jni.cpp
• 43b7e9f: 8346713: [testsuite] NeverActAsServerClassMachine breaks TestPLABAdaptToMinTLABSize.java TestPinnedHumongousFragmentation.java TestPinnedObjectContents.java
• 249f141: 8346737: GenShen: Generational memory pools should not report zero for maximum capacity
• d562d3c: 8343882: BasicAnnoTests doesn't handle multiple annotations at the same position
• 7ba969a: 8346739: jpackage tests failed after JDK-8345259
• b8e40b9: 8346688: GenShen: Missing metadata trigger log message
• d2a4863: 8346690: Shenandoah: Fix log message for end of GC usage report
• bcb1bda: 8345259: Disallow ALL-MODULE-PATH without explicit --module-path
• 054c644: 8346667: Doccheck: warning about missing before

• ... and 89 more: https://git.openjdk.org/jdk/compare/db9eab3f29e9cb26a8c0a7c31c55aaf140f21bed...master

Your commit was automatically rebased without conflicts.

[openjdk]

@dholmes-ora Pushed as commit cd15ebb.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.