1/* 2 * Copyright (c) 2010, 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 26package jdk.nashorn.internal.objects.annotations; 27 28import java.lang.annotation.ElementType; 29import java.lang.annotation.Retention; 30import java.lang.annotation.RetentionPolicy; 31import java.lang.annotation.Target; 32import java.lang.invoke.MethodHandle; 33import jdk.dynalink.CallSiteDescriptor; 34import jdk.dynalink.linker.LinkRequest; 35import jdk.nashorn.internal.runtime.ScriptFunction; 36import jdk.nashorn.internal.runtime.UnwarrantedOptimismException; 37 38/** 39 * The SpecializedFunction annotation is used to flag more type specific 40 * functions than the standard one in the native objects. 41 */ 42@Retention(RetentionPolicy.RUNTIME) 43@Target(ElementType.METHOD) 44public @interface SpecializedFunction { 45 46 /** 47 * Functionality for testing if we are allowed to link a specialized 48 * function the first time we encounter it. Then the guard will handle the 49 * rest of the invocations. 50 * 51 * This is the same for all callsites in Nashorn; the first time a callsite is 52 * linked, we have to manually check that the linkage is OK. Even if we add 53 * a guard and it fails upon the first try, this is not good enough. 54 * (Symmetrical to how it works everywhere else in the Nashorn runtime.) 55 * 56 * Here we abstract out a few of the most common link guard checks. 57 */ 58 public static abstract class LinkLogic { 59 /** 60 * Empty link logic instance - this is the default. 61 * "no special linking or runtime guard behavior" 62 */ 63 public static final LinkLogic EMPTY_INSTANCE = new Empty(); 64 65 /** Empty link logic class - allow all linking, no guards. */ 66 private static final class Empty extends LinkLogic { 67 @Override 68 public boolean canLink(final Object self, final CallSiteDescriptor desc, final LinkRequest request) { 69 return true; 70 } 71 72 @Override 73 public boolean isEmpty() { 74 return true; 75 } 76 } 77 78 /** 79 * Get the class representing the empty link logic. 80 * 81 * @return class representing empty link logic 82 */ 83 public static Class<? extends LinkLogic> getEmptyLinkLogicClass() { 84 return Empty.class; 85 } 86 87 /** 88 * Should this callsite relink when an exception is thrown? 89 * 90 * @return the relink exception, or {@code null} if none 91 */ 92 public Class<? extends Throwable> getRelinkException() { 93 return null; 94 } 95 96 /** 97 * Is this link logic class empty - i.e., no special linking logic 98 * supplied? 99 * 100 * @param clazz class to check 101 * 102 * @return {@code true} if this link logic is empty 103 */ 104 public static boolean isEmpty(final Class<? extends LinkLogic> clazz) { 105 return clazz == Empty.class; 106 } 107 108 /** 109 * Is this link logic instance empty - i.e., no special linking logic 110 * supplied? 111 * 112 * @return {@code true} if this link logic instance is empty 113 */ 114 public boolean isEmpty() { 115 return false; 116 } 117 118 /** 119 * Given a callsite, can we link this method based on the receiver and 120 * parameters? 121 * 122 * @param self receiver 123 * @param desc callsite descriptor 124 * @param request link request 125 * 126 * @return {@code true} if we can link this callsite at this time 127 */ 128 public abstract boolean canLink(final Object self, final CallSiteDescriptor desc, final LinkRequest request); 129 130 /** 131 * Given a callsite, do we require an extra guard for specialization to 132 * go through? 133 * 134 * @param self receiver 135 * 136 * @return {@code true} if a guard is to be woven into the callsite 137 */ 138 public boolean needsGuard(final Object self) { 139 return true; 140 } 141 142 /** 143 * Given a callsite, and optional arguments, do we need an extra guard 144 * for specialization to go through? This guard can be a function of 145 * the arguments too. 146 * 147 * @param self receiver 148 * @param args arguments 149 * 150 * @return {@code true} if a guard is to be woven into the callsite 151 */ 152 public boolean needsGuard(final Object self, final Object... args) { 153 return true; 154 } 155 156 /** 157 * Given a callsite, and optional arguments, return any extra guard we 158 * might need for specialization as a method handle. 159 * 160 * @return methodhandle for guard, or null if no guard is needed 161 */ 162 public MethodHandle getGuard() { 163 return null; 164 } 165 166 /** 167 * Check, given a link request and a receiver, if this specialization 168 * fits This is used by the linker in {@link ScriptFunction} to figure 169 * out if an optimistic builtin can be linked when first discovered 170 * 171 * @param self receiver 172 * @param desc callsite descriptor 173 * @param request link request 174 * 175 * @return {@code true} if we can link, {@code false} otherwise - that 176 * means we have to pick a non specialized target 177 */ 178 public boolean checkLinkable(final Object self, final CallSiteDescriptor desc, final LinkRequest request) { 179 // check the link guard, if it says we can link, go ahead 180 return canLink(self, desc, request); 181 } 182 } 183 184 /** 185 * Name override for return value polymorphism, for example we can't have 186 * pop(V)I and pop(V)D in the same Java class, so they need to be named, 187 * e.g., popInt(V)I and popDouble(V)D for disambiguation, however, their 188 * names still need to resolve to "pop" to JavaScript so we can still 189 * specialize on return values and so that the linker can find them. 190 * 191 * @return name, "" means no override, use the Java function name, e.g. 192 * "push" 193 */ 194 String name() default ""; 195 196 /** 197 * Return the guard for this specialized function. The default is no guard. 198 * 199 * @return guard 200 */ 201 Class<?> linkLogic() default LinkLogic.Empty.class; 202 203 /** 204 * @return whether this is a specialized constructor. 205 */ 206 boolean isConstructor() default false; 207 208 /** 209 * Can this function throw {@link UnwarrantedOptimismException}s? This works 210 * just like the normal functions, but we need the function to be 211 * immutable/non-state modifying, as we can't generate continuations for 212 * native code. Luckily a lot of the methods we want to specialize have this 213 * property. 214 * 215 * @return whether this function can throw {@link UnwarrantedOptimismException}. 216 */ 217 boolean isOptimistic() default false; 218 219 /** 220 * Is it safe to convert non-numeric arguments to numbers for this function's primitive numeric parameters? 221 * This is true for many built-in functions which expect numeric arguments, but not for those that 222 * expect generic arguments and just have specializations with numeric params to avoid boxing overhead. 223 * The default value is {@code true} because that is by far the most common case. 224 * 225 * @return true if it is safe to convert arguments to numbers 226 */ 227 boolean convertsNumericArgs() default true; 228} 229