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

rgithubli · 2025-08-22T18:36:04Z

Add documentation of Shenandoah to java man page

Aside from -XX:+UseShenandoahGC, I picked flags from shenandoah_globals.hpp that are at product level but not experimental / diagnostic to avoid overwhelming info. Two additional flags match: ShenandoahGCMode and ShenandoahGCHeuristics

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-8246037: Shenandoah: update man pages to mention -XX:+UseShenandoahGC (Enhancement - P4)

Reviewers

William Kemper (@earthling-amzn - Reviewer) Review applies to cbf1819a
Y. Srinivas Ramakrishna (@ysramakrishna - Reviewer)
Cesar Soares Lucas (@JohnTortugo - Committer) Review applies to 1c8d334a

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 26907

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

Using diff file

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

Using Webrev

Link to Webrev Comment

bridgekeeper · 2025-08-22T18:36:44Z

👋 Welcome back rgithubli! 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 · 2025-08-22T18:37:05Z

@rgithubli 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:

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

Reviewed-by: ysr, wkemper, cslucas

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 140 new commits pushed to the master branch:

991ac9e: 8365407: Race condition in MethodTrainingData::verify()
80fb708: 8365175: Replace Unicode extension anchor elements with link tag
0d85f07: 8359174: tools/jlink/JLink20000Packages.java timed out
... and 137 more: https://git.openjdk.org/jdk/compare/ae0dac43c09377c87e9b0452618a5b32c8568150...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.

As you do not have Committer status in this project an existing Committer must agree to sponsor your change. Possible candidates are the reviewers of this PR (@earthling-amzn, @ysramakrishna, @JohnTortugo) but any other Committer may sponsor as well.

➡️ To flag this PR as ready for integration with the above commit message, type /integrate in a new comment. (Afterwards, your sponsor types /sponsor in a new comment to perform the integration).

openjdk · 2025-08-22T18:37:50Z

@rgithubli The following label will be automatically applied to this pull request:

graal

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

mlbridge · 2025-08-22T18:41:33Z

Webrevs

ysramakrishna · 2025-08-23T00:18:47Z

/label remove graal

openjdk · 2025-08-23T00:19:00Z

@ysramakrishna
The graal label was successfully removed.

rgithubli · 2025-08-23T00:22:02Z

/label add hotspot

openjdk · 2025-08-23T00:22:18Z

@rgithubli
The hotspot label was successfully added.

src/java.base/share/man/java.md

shipilev · 2025-08-25T11:18:24Z

src/java.base/share/man/java.md

+    `satb`
+    :   Snapshot-at-the-beginning concurrent GC (three pass mark-evac-update).


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.

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?

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.

src/java.base/share/man/java.md

shipilev · 2025-08-25T11:19:14Z

src/java.base/share/man/java.md

+    the GC cycle.
+
+    `static`
+    :   Trigger GC when free heap falls below the ShenandoahMinFreeThreshold.


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.

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?

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

rgithubli · 2025-08-27T22:56:29Z

Updated for other comments except for renaming satb: instead, I added additional explanation to say satb is a single generation GC, as well as generational shenandoah is also an satb gc.

src/java.base/share/man/java.md

ysramakrishna

One small comment/suggestion. Rest looks good to me.

Approving modulo that suggestion.

src/java.base/share/man/java.md

rgithubli · 2025-08-28T04:21:40Z

~~/integrate~~ Need approval again

openjdk · 2025-08-28T04:22:47Z

@rgithubli This pull request has not yet been marked as ready for integration.

ysramakrishna

Approved modulo a comment.

I also think we should to the extent possible make the listing of text common to man page and options list consistent. An example is the recent improvement you made in your most recent update to the man page for the heuristics option. There may be other changes to the man page that came about as a result of this review. It would make sense to make those changes, where applicable, also to shenandoah_globals. This latter need not hold up this ticket but can be addressed separately in a follow up.

ysramakrishna · 2025-08-28T17:43:12Z

src/java.base/share/man/java.md

+    Possible heuristics are the following (when `-XX:ShenandoahGCMode` is
+    `generational`, the only supported option is the default, `adaptive`):


Move the parenthetic part to the previous paragraph and out of parentheses.

shipilev · 2025-08-28T18:06:01Z

Make sure that someone outside Shenandoah devs looks at this patch to sanity check how it reads.

JohnTortugo

Ship it!

ysramakrishna

Re-reviewed. 🚢

(Apologies for all the bike-shedding!)

rgithubli · 2025-09-02T22:31:08Z

/integrate

openjdk · 2025-09-02T22:32:33Z

@rgithubli
Your change (at version 1c25fbb) is now ready to be sponsored by a Committer.

kdnilsen · 2025-09-02T23:48:23Z

/sponsor

openjdk · 2025-09-02T23:49:23Z

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

b50c11f: 8366195: Remove unnecessary quotes around -Ta ml64 assembler argument
991ac9e: 8365407: Race condition in MethodTrainingData::verify()
80fb708: 8365175: Replace Unicode extension anchor elements with link tag
... and 138 more: https://git.openjdk.org/jdk/compare/ae0dac43c09377c87e9b0452618a5b32c8568150...master

Your commit was automatically rebased without conflicts.

openjdk · 2025-09-02T23:49:31Z

@kdnilsen @rgithubli Pushed as commit 5052a7e.

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

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

66b9981

rgithubli marked this pull request as ready for review August 22, 2025 18:36

openjdk bot added graal graal-dev@openjdk.org rfr Pull request is ready for review labels Aug 22, 2025

Comment for aggressive. Indent.

a9d1f6a

openjdk bot removed the graal graal-dev@openjdk.org label Aug 23, 2025

openjdk bot removed the rfr Pull request is ready for review label Aug 23, 2025

openjdk bot added the hotspot hotspot-dev@openjdk.org label Aug 23, 2025

openjdk bot added the rfr Pull request is ready for review label Aug 23, 2025

shipilev reviewed Aug 25, 2025

View reviewed changes

Update for comments

1875874

earthling-amzn suggested changes Aug 27, 2025

View reviewed changes

src/java.base/share/man/java.md Show resolved Hide resolved

ysramakrishna approved these changes Aug 27, 2025

View reviewed changes

src/java.base/share/man/java.md Show resolved Hide resolved

openjdk bot added the ready Pull request is ready to be integrated label Aug 27, 2025

gen shen and heuristics

b319e2b

openjdk bot removed the ready Pull request is ready to be integrated label Aug 28, 2025

ysramakrishna approved these changes Aug 28, 2025

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Aug 28, 2025

Add shen hpp changes

cbf1819

openjdk bot removed the ready Pull request is ready to be integrated label Aug 28, 2025

earthling-amzn approved these changes Aug 28, 2025

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Aug 28, 2025

shen hpp changes

1c8d334

openjdk bot removed the ready Pull request is ready to be integrated label Aug 28, 2025

JohnTortugo approved these changes Aug 29, 2025

View reviewed changes

update for threshold wording

1c25fbb

ysramakrishna approved these changes Sep 2, 2025

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Sep 2, 2025

openjdk bot added the sponsor Pull request is ready to be sponsored label Sep 2, 2025

openjdk bot added the integrated Pull request has been integrated label Sep 2, 2025

openjdk bot closed this Sep 2, 2025

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review sponsor Pull request is ready to be sponsored labels Sep 2, 2025

rgithubli deleted the 8246037 branch September 2, 2025 23:54

		`satb`
		: Snapshot-at-the-beginning concurrent GC (three pass mark-evac-update).

		Possible heuristics are the following (when `-XX:ShenandoahGCMode` is
		`generational`, the only supported option is the default, `adaptive`):

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

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

Uh oh!

Conversation

rgithubli commented Aug 22, 2025 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewers

Reviewing

Uh oh!

bridgekeeper bot commented Aug 22, 2025

Uh oh!

openjdk bot commented Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openjdk bot commented Aug 22, 2025

Uh oh!

mlbridge bot commented Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

ysramakrishna commented Aug 23, 2025

Uh oh!

openjdk bot commented Aug 23, 2025

Uh oh!

rgithubli commented Aug 23, 2025

Uh oh!

openjdk bot commented Aug 23, 2025

Uh oh!

Uh oh!

shipilev Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

rgithubli Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

ysramakrishna Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

shipilev Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

rgithubli Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

ysramakrishna Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

rgithubli commented Aug 27, 2025

Uh oh!

Uh oh!

ysramakrishna left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rgithubli commented Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openjdk bot commented Aug 28, 2025

Uh oh!

ysramakrishna left a comment

Choose a reason for hiding this comment

Uh oh!

ysramakrishna Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

shipilev commented Aug 28, 2025

Uh oh!

JohnTortugo left a comment

Choose a reason for hiding this comment

Uh oh!

ysramakrishna left a comment

Choose a reason for hiding this comment

Uh oh!

rgithubli commented Sep 2, 2025

Uh oh!

openjdk bot commented Sep 2, 2025

Uh oh!

rgithubli commented Aug 22, 2025 •

edited by openjdk bot

Loading

openjdk bot commented Aug 22, 2025 •

edited

Loading

mlbridge bot commented Aug 22, 2025 •

edited

Loading

rgithubli commented Aug 28, 2025 •

edited

Loading