1 /*
   2  * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package jdk.internal;
  27 
  28 import java.lang.annotation.*;
  29 
  30 /**
  31  * The {@code @HotSpotIntrinsicCandidate} annotation is specific to the
  32  * HotSpot Virtual Machine. It indicates that an annotated method
  33  * may be (but is not guaranteed to be) intrinsified by the HotSpot VM. A method
  34  * is intrinsified if the HotSpot VM replaces the annotated method with hand-written
  35  * assembly and/or hand-written compiler IR -- a compiler intrinsic -- to improve
  36  * performance. The {@code @HotSpotIntrinsicCandidate} annotation is internal to the
  37  * Java libraries and is therefore not supposed to have any relevance for application
  38  * code.
  39  *
  40  * Maintainers of the Java libraries must consider the following when
  41  * modifying methods annotated with {@code @HotSpotIntrinsicCandidate}.
  42  *
  43  * <ul>
  44  * <li>When modifying a method annotated with {@code @HotSpotIntrinsicCandidate},
  45  * the corresponding intrinsic code in the HotSpot VM implementation must be
  46  * updated to match the semantics of the annotated method.</li>
  47  * <li>For some annotated methods, the corresponding intrinsic may omit some low-level
  48  * checks that would be performed as a matter of course if the intrinsic is implemented
  49  * using Java bytecodes. This is because individual Java bytecodes implicitly check
  50  * for exceptions like {@code NullPointerException} and {@code ArrayStoreException}.
  51  * If such a method is replaced by an intrinsic coded in assembly language, any
  52  * checks performed as a matter of normal bytecode operation must be performed
  53  * before entry into the assembly code. These checks must be performed, as
  54  * appropriate, on all arguments to the intrinsic, and on other values (if any) obtained
  55  * by the intrinsic through those arguments. The checks may be deduced by inspecting
  56  * the non-intrinsic Java code for the method, and determining exactly which exceptions
  57  * may be thrown by the code, including undeclared implicit {@code RuntimeException}s.
  58  * Therefore, depending on the data accesses performed by the intrinsic,
  59  * the checks may include:
  60  *
  61  *  <ul>
  62  *  <li>null checks on references</li>
  63  *  <li>range checks on primitive values used as array indexes</li>
  64  *  <li>other validity checks on primitive values (e.g., for divide-by-zero conditions)</li>
  65  *  <li>store checks on reference values stored into arrays</li>
  66  *  <li>array length checks on arrays indexed from within the intrinsic</li>
  67  *  <li>reference casts (when formal parameters are {@code Object} or some other weak type)</li>
  68  *  </ul>
  69  *
  70  * </li>
  71  *
  72  * <li>Note that the receiver value ({@code this}) is passed as a extra argument
  73  * to all non-static methods. If a non-static method is an intrinsic, the receiver
  74  * value does not need a null check, but (as stated above) any values loaded by the
  75  * intrinsic from object fields must also be checked. As a matter of clarity, it is
  76  * better to make intrinisics be static methods, to make the dependency on {@code this}
  77  * clear. Also, it is better to explicitly load all required values from object
  78  * fields before entering the intrinsic code, and pass those values as explicit arguments.
  79  * First, this may be necessary for null checks (or other checks). Second, if the
  80  * intrinsic reloads the values from fields and operates on those without checks,
  81  * race conditions may be able to introduce unchecked invalid values into the intrinsic.
  82  * If the intrinsic needs to store a value back to an object field, that value should be
  83  * returned explicitly from the intrinsic; if there are multiple return values, coders
  84  * should consider buffering them in an array. Removing field access from intrinsics
  85  * not only clarifies the interface with between the JVM and JDK; it also helps decouple
  86  * the HotSpot and JDK implementations, since if JDK code before and after the intrinsic
  87  * manages all field accesses, then intrinsics can be coded to be agnostic of object
  88  * layouts.</li>
  89  *
  90  * Maintainers of the HotSpot VM must consider the following when modifying
  91  * intrinsics.
  92  *
  93  * <ul>
  94  * <li>When adding a new intrinsic, make sure that the corresponding method
  95  * in the Java libraries is annotated with {@code @HotSpotIntrinsicCandidate}
  96  * and that all possible call sequences that result in calling the intrinsic contain
  97  * the checks omitted by the intrinsic (if any).</li>
  98  * <li>When modifying an existing intrinsic, the Java libraries must be updated
  99  * to match the semantics of the intrinsic and to execute all checks omitted
 100  * by the intrinsic (if any).</li>
 101  * </ul>
 102  *
 103  * Persons not directly involved with maintaining the Java libraries or the
 104  * HotSpot VM can safely ignore the fact that a method is annotated with
 105  * {@code @HotSpotIntrinsicCandidate}.
 106  *
 107  * The HotSpot VM defines (internally) a list of intrinsics. Not all intrinsic
 108  * are available on all platforms supported by the HotSpot VM. Furthermore,
 109  * the availability of an intrinsic on a given platform depends on the
 110  * configuration of the HotSpot VM (e.g., the set of VM flags enabled).
 111  * Therefore, annotating a method with {@code @HotSpotIntrinsicCandidate} does
 112  * not guarantee that the marked method is intrinsified by the HotSpot VM.
 113  *
 114  * If the {@code CheckIntrinsics} VM flag is enabled, the HotSpot VM checks
 115  * (when loading a class) that (1) all methods of that class that are also on
 116  * the VM's list of intrinsics are annotated with {@code @HotSpotIntrinsicCandidate}
 117  * and that (2) for all methods of that class annotated with
 118  * {@code @HotSpotIntrinsicCandidate} there is an intrinsic in the list.
 119  *
 120  * @since 1.9
 121  */
 122 @Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
 123 @Retention(RetentionPolicy.RUNTIME)
 124 public @interface HotSpotIntrinsicCandidate {
 125 }