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

[John Rose]

On Nov 30, 2015, at 9:40 AM, Paul Sandoz <paul.sandoz at oracle.com> wrote:
> 
> Hi,
> 
> Please review:
> 
>  http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8144223-move-stable-force-dont-inline-jdk/webrev/
>  http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8144223-move-stable-force-dont-inline-hotspot/webrev/
> 
> This moves the package private annotations j.l.invoke.{ForceInline, DontInline, Stable} to public annotations of the same name in the non-exported (at least for unqualified exports) package jdk.internal.vm.annotation where @Contended lives (in hs-rt not currently hs-comp) and where HotSpotIntrinsicCandidate will move to.
> 
> The intent is these annotations can be used sparingly in classes in java.base packages other than java.lang.invoke. From the issue description:
> 
> https://bugs.openjdk.java.net/browse/JDK-8144223
> 
>> 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.

(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/

— 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