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

[rgithubli]

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) 🔄 Re-review required (review applies to cbf1819a)
• Y. Srinivas Ramakrishna (@ysramakrishna - Reviewer) 🔄 Re-review required (review applies to b319e2b9)
• Cesar Soares Lucas (@JohnTortugo - Committer)

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]

👋 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]

@rgithubli This change is no longer ready for integration - check the PR body for details.

[openjdk]

@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]

Webrevs

• 05: Full - Incremental (1c8d334a)
• 04: Full - Incremental (cbf1819a)
• 03: Full - Incremental (b319e2b9)
• 02: Full - Incremental (18758749)
• 01: Full - Incremental (a9d1f6a3)
• 00: Full (66b99814)

[ysramakrishna]

/label remove graal

[openjdk]

@ysramakrishna
The graal label was successfully removed.

[rgithubli]

/label add hotspot

[openjdk]

@rgithubli
The hotspot label was successfully added.

[shipilev]

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.

[rgithubli]

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?

[ysramakrishna]

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.

[shipilev]

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.

[rgithubli]

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?

[ysramakrishna]

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]

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.

[ysramakrishna]

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

Approving modulo that suggestion.

[rgithubli]

/integrate Need approval again

[openjdk]

@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]

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

[shipilev]

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

[JohnTortugo]

Ship it!