[crac] RFR: CRaC related documentation in JDK classes using custom tag [v3]

[Anton Kozlov]

On Mon, 3 Jul 2023 13:00:29 GMT, Radim Vansa <rvansa at openjdk.org> wrote:

>> As proposed in https://mail.openjdk.org/pipermail/crac-dev/2023-February/000496.html I am adding some CRaC related documentation.
>
> Radim Vansa has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains four additional commits since the last revision:
> 
>  - Updated wording
>  - Merge branch 'crac' into docs
>  - Add timers related docs
>  - CRaC related documentation in JDK classes using custom tag

Looks mostly good!

src/java.base/share/classes/java/lang/System.java line 789:

> 787:      * @crac While the API note above discourages from changing system properties during
> 788:      * runtime it is actually quite common after restore from a checkpoint. The application
> 789:      * can {@link javax.crac.Context#register(javax.crac.Resource) register}

> Changing a standard system property may have unpredictable results unless otherwise specified.
> Property values may be cached during initialization or on first use.
> Setting a standard property after initialization using ... may not have the desired effect.

The comment above is about standard properties, while update of user properties should fine. I propose to change to "Properties can be updated after restore. ..."

src/java.base/share/classes/java/lang/System.java line 1108:

> 1106:      * @crac While environment variables are typically constant through
> 1107:      * the lifetime of a process these can change after restore from
> 1108:      * a checkpoint. The application can {@link javax.crac.Context#register(javax.crac.Resource) register}

"Environment variables can change after restore. ..." ?

src/java.base/unix/classes/java/net/PlainSocketImpl.java line 39:

> 37:  * @crac The socket is automatically closed before checkpoint and reopened
> 38:  * after restore; there is no handling needed from the application side.
> 39:  *

We close and reopen the auxiliary unconnected socket used for "preClose" (dup2 of the aux socket on the being closed socket) -- to close the target but prevent immediate reuse of the FD.

Thus, the aux socket is completely an implementation detail and doesn't need to be documented.

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

PR Review: https://git.openjdk.org/crac/pull/51#pullrequestreview-1513218249
PR Review Comment: https://git.openjdk.org/crac/pull/51#discussion_r1252242478
PR Review Comment: https://git.openjdk.org/crac/pull/51#discussion_r1252243114
PR Review Comment: https://git.openjdk.org/crac/pull/51#discussion_r1252246172