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
rgithubli wants to merge 7 commits into from
Closed

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

Show file tree
Hide file tree
Changes from all commits
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
6 changes: 4 additions & 2 deletions src/hotspot/share/gc/shenandoah/shenandoah_globals.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,10 +141,12 @@
"GC heuristics to use. This fine-tunes the GC mode selected, " \
"by choosing when to start the GC, how much to process on each " \
"cycle, and what other features to automatically enable. " \
"Possible values are:" \
"When -XX:ShenandoahGCMode is generational, the only supported " \
"option is the default, adaptive. Possible values are:" \
" adaptive - adapt to maintain the given amount of free heap " \
"at all times, even during the GC cycle;" \
" static - trigger GC when free heap falls below the threshold;" \
" static - trigger GC when free heap falls below a specified " \
"threshold;" \
" aggressive - run GC continuously, try to evacuate everything;" \
" compact - run GC more frequently and with deeper targets to " \
"free up more memory.") \
Expand Down
40 changes: 40 additions & 0 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 @@ -2883,6 +2883,46 @@ Java HotSpot VM.
expensive operations. Using a lower value will cause heap memory to be
uncommitted earlier, at the risk of soon having to commit it again.

`-XX:+UseShenandoahGC`
: Enables the use of the Shenandoah garbage collector. This is a low pause
time, concurrent garbage collector. Its pause times are not proportional to
the size of the heap. Shenandoah garbage collector can work with compressed
pointers. See `-XX:UseCompressedOops` for further information about
compressed pointers.

`-XX:ShenandoahGCMode=`*mode*
: Sets the GC mode for Shenandoah GC to use. By default, this option is set
to `satb`. Among other things, this defines which barriers are in use.
Possible mode values include the following:

`satb`
: Snapshot-at-the-beginning concurrent GC (three pass mark-evac-update).
Comment on lines +2898 to +2899
Copy link
Member

@shipilev shipilev Aug 25, 2025

Choose a reason for hiding this comment

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

This is a long-standing problem with the name. It kinda implies generational is not satb. It actually is. Maybe we should rename satb to single or something. A lot of bikeshedding would ensue.

Copy link
Contributor Author

@rgithubli rgithubli Aug 25, 2025

Choose a reason for hiding this comment

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

Renaming the value of an existing jvm arg sounds intrusive, unless we can add an alias link from satb to single? Alternatively, we probably can add comment in generational to indicate it's also satb?

Copy link
Member

@ysramakrishna ysramakrishna Aug 26, 2025

Choose a reason for hiding this comment

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

I agree. For non-experimental options, we can follow the established deprecate & rename protocol.

May be we could, in the inerim, add verbage in the description to avoid the confusion in the current naming as described by Aleksey.

It is a single generation GC.

`generational`
: It is also a snapshot-at-the-beginning and concurrent GC, but it is
generational. Please see [JEP 404](https://openjdk.org/jeps/404) and
[JEP 521](https://openjdk.org/jeps/521) for its advantages and risks.

`-XX:ShenandoahGCHeuristics=`*heuristics*
: Sets the heuristics for Shenandoah GC to use. By default, this option is
set to `adaptive`. This fine-tunes the GC mode selected, by choosing when
to start the GC, how much to process on each cycle, and what other features
to automatically enable. When `-XX:ShenandoahGCMode` is `generational`, the
only supported option is the default, `adaptive`.

Possible heuristics are the following:

`adaptive`
: To maintain the given amount of free heap at all times, even during
the GC cycle.

`static`
: Trigger GC when free heap falls below a specified threshold.

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

## Deprecated Java Options

These `java` options are deprecated and might be removed in a future JDK
Expand Down