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
