8144223: Move j.l.invoke.{ForceInline, DontInline, Stable} to jdk.internal.vm.annotation package

[Paul Sandoz]

> On 30 Nov 2015, at 20:20, John Rose <john.r.rose at oracle.com> wrote:
>> 
>>> The annotations j.l.invoke.{ForceInline, DontInline, Stable} are currently package private but could have use outside that package if used carefully and sparingly. For example:
>>> 
>>> 1) Methods on Atomic*FieldUpdater classes may benefit from @ForceInline, as would array support methods of JDK-8136924 to preserve existing inlining characteristics.
>>> 2) Reference.reachabilityFence (JDK-8133348) could be annotated with @DontInline rather than explicitly making the method signature known to the VM.
>>> 3) The alias jdk.vm.ci.hotspot.Stable could potentially be removed.
>> 
>> I am especially interested if 3) is possible, it seems so from my limited knowledge.
> 
> It's a good move, now that we have a module system which can limit the accidental use of such things.
> 
> The javadoc for @ForceInline and @DontInline should both carry strong disclaimers about sparing usage.  Suggest:
> 
>> This annotation must be used sparingly.  It is useful when the only reasonable alternative is to bind the name of a specific method into the HotSpot JVM for special handling by the inlining policy.  This annotation must not be relied on as an alternative to avoid tuning the JVM's inlining policy.  In a few cases, it may act as a temporary workaround until the profiling and inlining performed by the JVM is sufficiently improved.
> 

Done.


> (It is an odd thing for javadoc to refer the user to JVM internals, but reasonable in this case, since the user base of the annotations is maintainers of the JDK itself.)
> 
> A grammar upgrade:  s/Annotated methods.constructors of classes/Annotations on methods or constructors of classes/
> s/Annotated fields of classes/Annotations on fields of classes/
> 

Done. Thanks.

I also took a stab at tweaking @Stable:

http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8144223-move-stable-force-dont-inline-jdk/webrev/

* <p>
* Fields which are declared {@code final} may also be annotated as stable.
* Since final fields already behave as stable values, such an annotation
* conveys no additional information regarding change of the field's value, but
* still conveys information regarding change of additional components values if
* the type of the field is an array type (as described above).
* <p>
* The HotSpot VM relies on this annotation to promote a non-null (resp.,
* non-zero) component value to a constant, thereby enabling superior
* optimizations of code depending on such a value (such as constant folding).
* More specifically, the HotSpot VM will process non-null stable fields (final
* or otherwise) in a similar manner to static final fields with respect to
* promoting the field's value to a constant.  Thus, placing aside the
* differences for null/non-null values and arrays, a final stable field is
* treated as if it is really final from both the Java language and the HotSpot
* VM.
* <p>
* It is (currently) undefined what happens if a field annotated as stable
* is given a third value (by explicitly updating a stable field, a component of
* a stable array, or a final stable field via reflection or other means).
* Since the HotSpot VM promotes a non-null component value to constant, it may
* be that the Java memory model would appear to be broken, if such a constant
* (the second value of the field) is used as the value of the field even after
* the field value has changed.

Paul.

> — John
> 
> P.S. Some day, I suppose, we can get lazy evaluation worked into the JVM semantics, and available to all Java programmers.  (If it is not hardwired as in [1], it may require a property mechanism in order to control the writes.)  Until then, we have an unenforced "gentleman's agreement", as described by the javadoc of @Stable.
> 
> [1]: http://cr.openjdk.java.net/~jrose/draft/lazy-final.html