Proposal for documentation and snapsafety

[Radim Vansa]

Hi all,

Anton asked me to have a look on the ways we could communicate 
CRaC-specific behavior to users. I went through this mailing list to see 
this has been discussed in the past quite a bit, but I'd like to get 
some consensus and start working on improving the user experience.

The documentation part should be pretty straightforward; I think that we 
could use custom tag [1] @crac that will usher the CRaC specific 
information. This will make it easier to full-text search it, and 
exclude in builds that won't support CRaC (if there'll be any). While 
the main target is the public API this annotation should be used in 
places that should not be used directly, e.g. sun.security.* packages 
that were 'fixed up' for CRaC. It is perfectly fine to add a 
documentation with this tag to places that are *not* changed, e.g. the 
j.u.Random explaining the reasoning behind that.

While all JDK code can be eventually fixed in a similar way to 
SecureRandom I think that it's clear that not everything can be 
encapsulated. A good example are the environment variables, but also 
number of processors and many others [2]. I propose to tag any 
method/constructor that returns data that could be expected to stay 
constant in non-C/R app but often changes after restore, or an object 
that will need handling through a registered Resource, with 
@CracSensitive (3) annotation. We will provide a tool that will report 
places that could call these methods, unless marked with @CracSafe 
annotation. This tool could work in a static way (scanning set of JARs, 
probably with a thin Maven plugin as well?) and as a javaagent, scanning 
classes as these get loaded.

Naturally not all code invoking non-snap-safe methods is from user code, 
many cases come from the libraries. Alternative way to allow-list places 
calling @CracSensitive methods in places that cannot be changed directly 
would be provided, though eventually we aim at encouraging that the 
libraries adopt the @CracSafe internally.

Non-goal: Any means for *making* the libraries snap-safe (e.g. the 
Substitutions) are out of scope of this proposal.

I will start prototyping this, though I'll welcome any suggestions and 
concerns.

Radim


[1] 
https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#tag

[2] https://github.com/eclipse-openj9/openj9/issues/12484

(3) We could use @SnapSensitive and @SnapSafe instead