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 // Android-note: HotSpot-specific implementation notes not relevant for Android. 31 /** 32 * The {@code @HotSpotIntrinsicCandidate} annotation is specific to the 33 * HotSpot Virtual Machine. It indicates that an annotated method 34 * may be (but is not guaranteed to be) intrinsified by the HotSpot VM. A method 35 * is intrinsified if the HotSpot VM replaces the annotated method with hand-written 36 * assembly and/or hand-written compiler IR -- a compiler intrinsic -- to improve 37 * performance. The {@code @HotSpotIntrinsicCandidate} annotation is internal to the 38 * Java libraries and is therefore not supposed to have any relevance for application 39 * code. 40 * 41 * Maintainers of the Java libraries must consider the following when 42 * modifying methods annotated with {@code @HotSpotIntrinsicCandidate}. 43 * 44 * <ul> 45 * <li>When modifying a method annotated with {@code @HotSpotIntrinsicCandidate}, 46 * the corresponding intrinsic code in the HotSpot VM implementation must be 47 * updated to match the semantics of the annotated method.</li> 48 * <li>For some annotated methods, the corresponding intrinsic may omit some low-level 49 * checks that would be performed as a matter of course if the intrinsic is implemented 50 * using Java bytecodes. This is because individual Java bytecodes implicitly check 51 * for exceptions like {@code NullPointerException} and {@code ArrayStoreException}. 52 * If such a method is replaced by an intrinsic coded in assembly language, any 53 * checks performed as a matter of normal bytecode operation must be performed 54 * before entry into the assembly code. These checks must be performed, as 55 * appropriate, on all arguments to the intrinsic, and on other values (if any) obtained 56 * by the intrinsic through those arguments. The checks may be deduced by inspecting 57 * the non-intrinsic Java code for the method, and determining exactly which exceptions 58 * may be thrown by the code, including undeclared implicit {@code RuntimeException}s. 59 * Therefore, depending on the data accesses performed by the intrinsic, 60 * the checks may include: 61 * 62 * <ul> 63 * <li>null checks on references</li> 64 * <li>range checks on primitive values used as array indexes</li> 65 * <li>other validity checks on primitive values (e.g., for divide-by-zero conditions)</li> 66 * <li>store checks on reference values stored into arrays</li> 67 * <li>array length checks on arrays indexed from within the intrinsic</li> 68 * <li>reference casts (when formal parameters are {@code Object} or some other weak type)</li> 69 * </ul> 70 * 71 * </li> 72 * 73 * <li>Note that the receiver value ({@code this}) is passed as a extra argument 74 * to all non-static methods. If a non-static method is an intrinsic, the receiver 75 * value does not need a null check, but (as stated above) any values loaded by the 76 * intrinsic from object fields must also be checked. As a matter of clarity, it is 77 * better to make intrinisics be static methods, to make the dependency on {@code this} 78 * clear. Also, it is better to explicitly load all required values from object 79 * fields before entering the intrinsic code, and pass those values as explicit arguments. 80 * First, this may be necessary for null checks (or other checks). Second, if the 81 * intrinsic reloads the values from fields and operates on those without checks, 82 * race conditions may be able to introduce unchecked invalid values into the intrinsic. 83 * If the intrinsic needs to store a value back to an object field, that value should be 84 * returned explicitly from the intrinsic; if there are multiple return values, coders 85 * should consider buffering them in an array. Removing field access from intrinsics 86 * not only clarifies the interface with between the JVM and JDK; it also helps decouple 87 * the HotSpot and JDK implementations, since if JDK code before and after the intrinsic 88 * manages all field accesses, then intrinsics can be coded to be agnostic of object 89 * layouts.</li> 90 * 91 * Maintainers of the HotSpot VM must consider the following when modifying 92 * intrinsics. 93 * 94 * <ul> 95 * <li>When adding a new intrinsic, make sure that the corresponding method 96 * in the Java libraries is annotated with {@code @HotSpotIntrinsicCandidate} 97 * and that all possible call sequences that result in calling the intrinsic contain 98 * the checks omitted by the intrinsic (if any).</li> 99 * <li>When modifying an existing intrinsic, the Java libraries must be updated 100 * to match the semantics of the intrinsic and to execute all checks omitted 101 * by the intrinsic (if any).</li> 102 * </ul> 103 * 104 * Persons not directly involved with maintaining the Java libraries or the 105 * HotSpot VM can safely ignore the fact that a method is annotated with 106 * {@code @HotSpotIntrinsicCandidate}. 107 * 108 * The HotSpot VM defines (internally) a list of intrinsics. Not all intrinsic 109 * are available on all platforms supported by the HotSpot VM. Furthermore, 110 * the availability of an intrinsic on a given platform depends on the 111 * configuration of the HotSpot VM (e.g., the set of VM flags enabled). 112 * Therefore, annotating a method with {@code @HotSpotIntrinsicCandidate} does 113 * not guarantee that the marked method is intrinsified by the HotSpot VM. 114 * 115 * If the {@code CheckIntrinsics} VM flag is enabled, the HotSpot VM checks 116 * (when loading a class) that (1) all methods of that class that are also on 117 * the VM's list of intrinsics are annotated with {@code @HotSpotIntrinsicCandidate} 118 * and that (2) for all methods of that class annotated with 119 * {@code @HotSpotIntrinsicCandidate} there is an intrinsic in the list. 120 * 121 * @since 9 122 */ 123 @Target({ElementType.METHOD, ElementType.CONSTRUCTOR}) 124 // Android-changed: RetentionPolicy.SOURCE is sufficient as this is no-op on Android. 125 // @Retention(RetentionPolicy.RUNTIME) 126 @Retention(RetentionPolicy.SOURCE) 127 public @interface HotSpotIntrinsicCandidate { 128 } 129