[crac] RFR: 8364554: [CRaC] Improve CRaC VM options' docs [v2]

[Radim Vansa]

On Sat, 2 Aug 2025 13:19:53 GMT, Timofei Pushkin <tpushkin at openjdk.org> wrote:

>> Besides some wording and formatting of VM options:
>> - Renames `CRaCAllowToSkipCheckpoint` to `CRaCSkipCheckpoint` since it makes the VM always skip checkpoints and not only in some cases
>> - Replaces `CRaCMaxHeapSizeBeforeCheckpoint == 0` with `FLAG_IS_DEFAULT(CRaCMaxHeapSizeBeforeCheckpoint)` because the docs 0 do not specify 0 as a special value
>
> Timofei Pushkin has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Improve wording for CRaCMinPid

src/hotspot/share/runtime/globals.hpp line 1962:

> 1960:                                                                             \
> 1961:   product(ccstr, CRaCCheckpointTo, nullptr, RESTORE_SETTABLE,               \
> 1962:           "Path to place the checkpoint image into")                        \

I think it is still important to state that the path leads to a directory.

src/hotspot/share/runtime/globals.hpp line 1965:

> 1963:                                                                             \
> 1964:   product(ccstr, CRaCRestoreFrom, nullptr, RESTORE_SETTABLE,                \
> 1965:           "Path to the image to restore from. If restore succeeds, the "    \

In case of CRIU it is not really replaced, the restored VM is a child process of launcher stub...

src/hotspot/share/runtime/globals.hpp line 1969:

> 1967:                                                                             \
> 1968:   product(uint, CRaCMinPid, 128,                                            \
> 1969:           "Mininal PID value for checkpointed process (Unix only)")         \

`Unix` -> `POSIX` (same as in java.md). Linux is not Unix.

src/hotspot/share/runtime/globals.hpp line 2006:

> 2004:           "use -Djdk.crac.resource-policies=...")                           \
> 2005:                                                                             \
> 2006:   product(bool, CRaCSkipCheckpoint, false, DIAGNOSTIC,                      \

Shouldn't we rather deprecate/obsolete the option altogether? Sounds like a predecessor to `simengine`, that is the preferred way. Looking into the implementation it seems that this will keep `jcmd` hanging if invoked from that, won't it?

src/hotspot/share/runtime/globals.hpp line 2017:

> 2015:                                                                             \
> 2016:   product(bool, CRaCTraceStartupTime, false, DIAGNOSTIC,                    \
> 2017:           "Trace restore startup time")                                     \

So "restore" or "startup"? :-) What about

> Print timestamp after successful restore by CRaC engine

In general, I think that this should be turned into unified logging configuration option. It's also weird that it is not restore-settable, you have to set that on checkpoint...

src/hotspot/share/runtime/globals.hpp line 2020:

> 2018:                                                                             \
> 2019:   product(bool, CRaCDoThrowCheckpointException, true, EXPERIMENTAL,         \
> 2020:           "Throw CheckpointException if non-checkpointable low-level "      \

I don't really see what's the purpose, and there's no test. Since it's experimental, can we obsolete it righ away?

src/java.base/share/man/java.md line 1086:

> 1084: 
> 1085: `-XX:CRaCRestoreFrom=`*directory*
> 1086: :   Restores an image created by `-XX:CRaCCheckpointTo`.

The "by" is a bit out of place, since the option does not immediately trigger creation of the image. How about
> Restores an image written on checkpoint into `-XX:CRaCCheckpointTo` 

?

-------------

PR Review Comment: https://git.openjdk.org/crac/pull/256#discussion_r2251614732
PR Review Comment: https://git.openjdk.org/crac/pull/256#discussion_r2251618398
PR Review Comment: https://git.openjdk.org/crac/pull/256#discussion_r2251621208
PR Review Comment: https://git.openjdk.org/crac/pull/256#discussion_r2251647598
PR Review Comment: https://git.openjdk.org/crac/pull/256#discussion_r2251672186
PR Review Comment: https://git.openjdk.org/crac/pull/256#discussion_r2251683432
PR Review Comment: https://git.openjdk.org/crac/pull/256#discussion_r2251698312