Skip to content

8246037: Shenandoah: update man pages to mention -XX:+UseShenandoahGC #26907

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 7 commits into from
Closed

8246037: Shenandoah: update man pages to mention -XX:+UseShenandoahGC #26907

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
66b9981
8246037: Shenandoah: update man pages to mention -XX:+UseShenandoahGC
rgithubli Aug 22, 2025
a9d1f6a
Comment for aggressive. Indent.
rgithubli Aug 22, 2025
1875874
Update for comments
rgithubli Aug 26, 2025
b319e2b
gen shen and heuristics
rgithubli Aug 28, 2025
cbf1819
Add shen hpp changes
rgithubli Aug 28, 2025
1c8d334
shen hpp changes
rgithubli Aug 28, 2025
1c25fbb
update for threshold wording
rgithubli Sep 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions src/java.base/share/man/java.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2900,7 +2900,7 @@ Java HotSpot VM.

`passive`
: Stop the world GC only (either degenerated or full). This mode is
diagnostic, and must be enabled via `-XX:+UnlockDiagnosticVMOptions`.
diagnostic, and must be enabled via `-XX:+UnlockDiagnosticVMOptions`.

`generational`
: Generational concurrent GC.
Expand All @@ -2919,7 +2919,8 @@ Java HotSpot VM.
: Trigger GC when free heap falls below the ShenandoahMinFreeThreshold.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here: ShenandoahMinFreeThreshold is experimental, it is not worth mentioning here. In fact, there are tunables for adaptive and compact as well, yet we do not (correctly!) mention them.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

True, other options respond to ShenandoahMinFreeThreshold as well. It's kinda hard to describe static option without mentioning the threshold.

  • We could make the doc vague as in the shenandoah_globals.hpp: trigger GC when free heap falls below the threshold.
  • I now wonder why static is a non experimental flag - it has to be used with other experimental flags. Maybe just drop static from man page as well?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

below a specified threshold might sound appropriately vague and render the flag unusable unless one consulted the code, underlining the experimental nature of it.

If the collector respects static as specified, it can be considered a good guardrail to use in anger. In fact, I know of teams that do in production. (For that matter, there are a couple who use compact as well.)

However, I am fine with eliding all experimental options, and in turn any non-experimental options that depend on experimental options (which however seems to be an anti-pattern to be avoided, if possible).


`aggressive`
: Run GC continuously, try to evacuate everything.
: Run GC continuously, try to evacuate everything. This heuristics is
diagnostic, and must be enabled via -XX:+UnlockDiagnosticVMOptions.

`compact`
: Run GC more frequently and with deeper targets to free up more memory.
Expand Down