RFR: 8221477: Inject os/cpu-specific constants into Unsafe from JVM

[Andrew Dinn]

Hi Peter,

Thanks for the last-minute recommendation!

On 05/04/2019 08:37, Peter Levart wrote:
> For a casual reader (like me) the comments in the UnsafeConstants for
> each field:
> 
>   69      * @implNote
>   70      * The actual value for this field is injected by the JVM.
> 
> ...make one wonder what is actually going on regarding the static
> initializer at the end of the class. Is it actually executed? Is it
> there just to silence the javac and prevent fields from becoming
> compile-time constants?

Regarding the static initializer ... there is an explanatory implNote
explaining the rationale for the static block in the class javadoc at
the top of the file. I agree this could be improved by explaining that
the block is executed and then its settings are overridden:

 * @implNote
 *
 * The JVM injects hardware-specific values into all the static fields
 * of this class during JVM initialization. The static initialization
 * block is executed when the class is initialized then JVM injection
 * updates the fields with the correct constants. The static block
 * is required to prevent the fields from being considered constant
 * variables, so the field values will be not be compiled directly into
 * any class that uses them.

Regarding the field Javadoc ... I understand that an OpenJDK dev might
want a correct and complete model for what exactly happens during init
however that is rather a moot point as regards semantics of the value in
the Java code. The nett effect is as the javadoc states -- the value is
injected by the JVM and, per the text above, that value identifies the
relevant hardware/os config parameter. So, I'll stop at expanding the
class-level comment.

> Just for the peace of mind of casual readers or perhaps someone that
> might later add a field to this class and try to initialize it in the
> static initializer, although I think this class is reserved for injected
> fields only...

Understood. I think the class-level comment already makes that latter
detail explicit and the revised version gives enough warning to devs.

I hope the above changes is acceptable.

regards,


Andrew Dinn
-----------
Senior Principal Software Engineer
Red Hat UK Ltd
Registered in England and Wales under Company Registration No. 03798903
Directors: Michael Cunningham, Michael ("Mike") O'Neill, Eric Shander