changeset 54578:803c31f428ff intrinsics-project

clarifying the API for IntrinsicCandidate
author vromero
date Tue, 29 Jan 2019 18:41:39 -0500
parents fcddff6177b4
children 7393d04a0b90
files src/java.base/share/classes/java/lang/compiler/IntrinsicCandidate.java
diffstat 1 files changed, 11 insertions(+), 1 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/lang/compiler/IntrinsicCandidate.java	Mon Jan 28 15:56:58 2019 -0500
+++ b/src/java.base/share/classes/java/lang/compiler/IntrinsicCandidate.java	Tue Jan 29 18:41:39 2019 -0500
@@ -27,7 +27,17 @@
 import java.lang.annotation.*;
 
 /**
- * Annotated method is a candidate for compile time optimization.
+ * Indicates an <i>intrinsic candidate</i>: a method whose invocation may be <i>intrinsified</i> by the compiler in a
+ * behaviorally-compatible way. Intrinsification generally involves the compiler recognizing when constant arguments
+ * are passed to a passed to a variable-arity method, where the overhead of boxing is significant. In some cases,
+ * the compiler can fold the entire invocation into a constant at compile time. In other cases, the compiler can generate
+ * bytecode that invokes a specialized method (based on the constant arguments) at run time.
+ * <p>
+ * The compiler is free to optimize a given invocation in source code differently in each
+ * compilation, and to optimize adjacent invocations of the same intrinsic candidate in source code in different ways.
+ * <p>
+ * This annotation may only be applied to {@code public} methods in classes of the {@code java.base} module.
+ * Applying it to other methods is not an error, but has no effect.
  *
  * @apiNote
  * This type's retention policy ensures that annotations of this type are not available through the reflection API.