changeset 54579:7393d04a0b90 intrinsics-project

more api notes
author vromero
date Tue, 29 Jan 2019 20:52:30 -0500
parents 803c31f428ff
children ea6826b20f20
files src/java.base/share/classes/java/io/PrintStream.java src/java.base/share/classes/java/io/PrintWriter.java src/java.base/share/classes/java/lang/String.java src/java.base/share/classes/java/lang/compiler/IntrinsicCandidate.java src/java.base/share/classes/java/util/Objects.java
diffstat 5 files changed, 75 insertions(+), 1 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/io/PrintStream.java	Tue Jan 29 18:41:39 2019 -0500
+++ b/src/java.base/share/classes/java/io/PrintStream.java	Tue Jan 29 20:52:30 2019 -0500
@@ -1001,6 +1001,11 @@
      *     out.format(format, args)
      * }</pre>
      *
+     * @implNote
+     * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
+     * if the {@code format} string is a constant expression. Note that the locale used depends on the
+     * default locale in effect <i>at compile time</i>.
+     *
      * @param  format
      *         A format string as described in <a
      *         href="../util/Formatter.html#syntax">Format string syntax</a>
@@ -1049,6 +1054,11 @@
      *     out.format(l, format, args)
      * }</pre>
      *
+     * @implNote
+     * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
+     * if the {@code format} string is a constant expression. Note that the locale used depends on the
+     * default locale in effect <i>at compile time</i>.
+     *
      * @param  l
      *         The {@linkplain java.util.Locale locale} to apply during
      *         formatting.  If {@code l} is {@code null} then no localization
@@ -1100,6 +1110,11 @@
      * regardless of any previous invocations of other formatting methods on
      * this object.
      *
+     * @implNote
+     * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
+     * if the {@code format} string is a constant expression. Note that the locale used depends on the
+     * default locale in effect <i>at compile time</i>.
+     *
      * @param  format
      *         A format string as described in <a
      *         href="../util/Formatter.html#syntax">Format string syntax</a>
@@ -1155,6 +1170,11 @@
      * Writes a formatted string to this output stream using the specified
      * format string and arguments.
      *
+     * @implNote
+     * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
+     * if the {@code format} string is a constant expression. Note that the locale used depends on the
+     * default locale in effect <i>at compile time</i>.
+     *
      * @param  l
      *         The {@linkplain java.util.Locale locale} to apply during
      *         formatting.  If {@code l} is {@code null} then no localization
--- a/src/java.base/share/classes/java/io/PrintWriter.java	Tue Jan 29 18:41:39 2019 -0500
+++ b/src/java.base/share/classes/java/io/PrintWriter.java	Tue Jan 29 20:52:30 2019 -0500
@@ -855,6 +855,11 @@
      *     out.format(format, args)
      * }</pre>
      *
+     * @implNote
+     * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
+     * if the {@code format} string is a constant expression. Note that the locale used depends on the
+     * default locale in effect <i>at compile time</i>.
+     *
      * @param  format
      *         A format string as described in <a
      *         href="../util/Formatter.html#syntax">Format string syntax</a>.
@@ -904,6 +909,11 @@
      *     out.format(l, format, args)
      * }</pre>
      *
+     * @implNote
+     * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
+     * if the {@code format} string is a constant expression. Note that the locale used depends on the
+     * default locale in effect <i>at compile time</i>.
+     *
      * @param  l
      *         The {@linkplain java.util.Locale locale} to apply during
      *         formatting.  If {@code l} is {@code null} then no localization
@@ -955,6 +965,11 @@
      * java.util.Locale#getDefault() Locale.getDefault()}, regardless of any
      * previous invocations of other formatting methods on this object.
      *
+     * @implNote
+     * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
+     * if the {@code format} string is a constant expression. Note that the locale used depends on the
+     * default locale in effect <i>at compile time</i>.
+     *
      * @param  format
      *         A format string as described in <a
      *         href="../util/Formatter.html#syntax">Format string syntax</a>.
@@ -1011,6 +1026,11 @@
      * string and arguments.  If automatic flushing is enabled, calls to this
      * method will flush the output buffer.
      *
+     * @implNote
+     * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
+     * if the {@code format} string is a constant expression. Note that the locale used depends on the
+     * default locale in effect <i>at compile time</i>.
+     *
      * @param  l
      *         The {@linkplain java.util.Locale locale} to apply during
      *         formatting.  If {@code l} is {@code null} then no localization
--- a/src/java.base/share/classes/java/lang/String.java	Tue Jan 29 18:41:39 2019 -0500
+++ b/src/java.base/share/classes/java/lang/String.java	Tue Jan 29 20:52:30 2019 -0500
@@ -2957,6 +2957,11 @@
      * Locale.getDefault(Locale.Category)} with
      * {@link java.util.Locale.Category#FORMAT FORMAT} category specified.
      *
+     * @implNote
+     * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
+     * if the {@code format} string is a constant expression. Note that the locale used depends on the
+     * default locale in effect <i>at compile time</i>.
+     *
      * @param  format
      *         A <a href="../util/Formatter.html#syntax">format string</a>
      *
@@ -2994,6 +2999,11 @@
      * Returns a formatted string using the specified locale, format string,
      * and arguments.
      *
+     * @implNote
+     * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
+     * if the {@code format} string is a constant expression. Note that the locale used depends on the
+     * default locale in effect <i>at compile time</i>.
+     *
      * @param  l
      *         The {@linkplain java.util.Locale locale} to apply during
      *         formatting.  If {@code l} is {@code null} then no localization
@@ -3042,6 +3052,11 @@
      * Locale.getDefault(Locale.Category)} with
      * {@link java.util.Locale.Category#FORMAT FORMAT} category specified.
      *
+     * @implNote
+     * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
+     * if the {@code format} string is a constant expression. Note that the locale used depends on the
+     * default locale in effect <i>at compile time</i>.
+     *
      * @param  args
      *         Arguments referenced by the format specifiers in the format
      *         string.  If there are more arguments than format specifiers, the
@@ -3078,6 +3093,11 @@
      * <a href="../util/Formatter.html#syntax">format</a>, the specified locale,
      * and  arguments.
      *
+     * @implNote
+     * An invocation of this method may be intrinsified {@link java.lang.compiler.IntrinsicCandidate}
+     * if the {@code format} string is a constant expression. Note that the locale used depends on the
+     * default locale in effect <i>at compile time</i>.
+     *
      * @param  l
      *         The {@linkplain java.util.Locale locale} to apply during
      *         formatting.  If {@code l} is {@code null} then no localization
--- a/src/java.base/share/classes/java/lang/compiler/IntrinsicCandidate.java	Tue Jan 29 18:41:39 2019 -0500
+++ b/src/java.base/share/classes/java/lang/compiler/IntrinsicCandidate.java	Tue Jan 29 20:52:30 2019 -0500
@@ -31,7 +31,8 @@
  * 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.
+ * bytecode that invokes a specialized method (based on the constant arguments or based on the types of all 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.
--- a/src/java.base/share/classes/java/util/Objects.java	Tue Jan 29 18:41:39 2019 -0500
+++ b/src/java.base/share/classes/java/util/Objects.java	Tue Jan 29 20:52:30 2019 -0500
@@ -138,6 +138,19 @@
     * value does not equal the hash code of that object reference.</b> This
     * value can be computed by calling {@link #hashCode(Object)}.
     *
+    * @implNote
+    * An invocation of this method may be intrinsified see {@link java.lang.compiler.IntrinsicCandidate}.
+    * <p>
+    * If all the arguments are constant expressions, then the compiler generates a hash code directly. It evaluates all
+    * the arguments, passes them to a helper method, and uses the integer result as the run-time value of the method invocation.
+    * Typically, the compiler uses {@code Arrays.hashCode} as the helper method, and emits an {@code ldc}
+    * instruction to load the (constant) integer result from the constant pool. If the integer result is small enough,
+    * then the compiler may encode it directly in an {@code sipush} instruction, avoiding the need for a constant pool entry.
+    * <p>
+    * If some arguments are not constant expressions, then the compiler may generate bytecode that generates a hash code for each
+    * argument in a type-specific way, and combines the results. No boxing of arguments into a varargs array is required,
+    * nor boxing of primitive arguments into numeric wrappers.
+    *
     * @param values the values to be hashed
     * @return a hash value of the sequence of input values
     * @see Arrays#hashCode(Object[])