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

[Remi Forax]

One annotation is missing, @TrueFinal,
currently only the fields of the classes of java.lang.invoke are considered as true final.

This annotation is also needed to improve the performance of the field updaters of j.u.c.a.
One can use @Stable instead but it seems awkward.

regards,
Rémi

----- Mail original -----
> De: "John Rose" <john.r.rose at oracle.com>
> À: "Paul Sandoz" <paul.sandoz at oracle.com>
> Cc: "hotspot compiler" <hotspot-compiler-dev at openjdk.java.net>, "hotspot-runtime-dev at openjdk.java.net runtime"
> <hotspot-runtime-dev at openjdk.java.net>
> Envoyé: Lundi 30 Novembre 2015 20:20:35
> Objet: Re: 8144223: Move j.l.invoke.{ForceInline, DontInline,	Stable} to jdk.internal.vm.annotation package
> 
> 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