1 /*
   2  * Copyright (c) 2015, 2018, 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.
   8  *
   9  * This code is distributed in the hope that it will be useful, but WITHOUT
  10  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12  * version 2 for more details (a copy is included in the LICENSE file that
  13  * accompanied this code).
  14  *
  15  * You should have received a copy of the GNU General Public License version
  16  * 2 along with this work; if not, write to the Free Software Foundation,
  17  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  18  *
  19  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  20  * or visit www.oracle.com if you need additional information or have any
  21  * questions.
  22  */
  23 
  24 
  25 package org.graalvm.compiler.api.directives;
  26 
  27 // JaCoCo Exclude
  28 
  29 /**
  30  * Directives that influence the compilation of methods by Graal. They don't influence the semantics
  31  * of the code, but they are useful for unit testing and benchmarking.
  32  */
  33 public final class GraalDirectives {
  34 
  35     public static final double LIKELY_PROBABILITY = 0.75;
  36     public static final double UNLIKELY_PROBABILITY = 1.0 - LIKELY_PROBABILITY;
  37 
  38     public static final double SLOWPATH_PROBABILITY = 0.0001;
  39     public static final double FASTPATH_PROBABILITY = 1.0 - SLOWPATH_PROBABILITY;
  40 
  41     /**
  42      * Directive for the compiler to fall back to the bytecode interpreter at this point.
  43      */
  44     public static void deoptimize() {
  45     }
  46 
  47     /**
  48      * Directive for the compiler to fall back to the bytecode interpreter at this point, invalidate
  49      * the compiled code and reprofile the method.
  50      */
  51     public static void deoptimizeAndInvalidate() {
  52     }
  53 
  54     /**
  55      * Directive for the compiler to fall back to the bytecode interpreter at this point, invalidate
  56      * the compiled code, record a speculation and reprofile the method.
  57      */
  58     public static void deoptimizeAndInvalidateWithSpeculation() {
  59     }
  60 
  61     /**
  62      * Returns a boolean value indicating whether the method is executed in Graal-compiled code.
  63      */
  64     public static boolean inCompiledCode() {
  65         return false;
  66     }
  67 
  68     /**
  69      * A call to this method will never be duplicated by control flow optimizations in the compiler.
  70      */
  71     public static void controlFlowAnchor() {
  72     }
  73 
  74     /**
  75      * Injects a probability for the given condition into the profiling information of a branch
  76      * instruction. The probability must be a value between 0.0 and 1.0 (inclusive).
  77      *
  78      * Example usage (it specifies that the likelihood for a to be greater than b is 90%):
  79      *
  80      * <code>
  81      * if (injectBranchProbability(0.9, a &gt; b)) {
  82      *    // ...
  83      * }
  84      * </code>
  85      *
  86      * There are predefined constants for commonly used probabilities (see
  87      * {@link #LIKELY_PROBABILITY} , {@link #UNLIKELY_PROBABILITY}, {@link #SLOWPATH_PROBABILITY},
  88      * {@link #FASTPATH_PROBABILITY} ).
  89      *
  90      * @param probability the probability value between 0.0 and 1.0 that should be injected
  91      */
  92     public static boolean injectBranchProbability(double probability, boolean condition) {
  93         assert probability >= 0.0 && probability <= 1.0;
  94         return condition;
  95     }
  96 
  97     /**
  98      * Injects an average iteration count of a loop into the probability information of a loop exit
  99      * condition. The iteration count specifies how often the condition is checked, i.e. in for and
 100      * while loops it is one more than the body iteration count, and in do-while loops it is equal
 101      * to the body iteration count. The iteration count must be >= 1.0.
 102      *
 103      * Example usage (it specifies that the expected iteration count of the loop condition is 500,
 104      * so the iteration count of the loop body is 499):
 105      *
 106      * <code>
 107      * for (int i = 0; injectIterationCount(500, i < array.length); i++) {
 108      *     // ...
 109      * }
 110      * </code>
 111      *
 112      * @param iterations the expected number of iterations that should be injected
 113      */
 114     public static boolean injectIterationCount(double iterations, boolean condition) {
 115         return injectBranchProbability(1. - 1. / iterations, condition);
 116     }
 117 
 118     /**
 119      * Consume a value, making sure the compiler doesn't optimize away the computation of this
 120      * value, even if it is otherwise unused.
 121      */
 122     @SuppressWarnings("unused")
 123     public static void blackhole(boolean value) {
 124     }
 125 
 126     /**
 127      * Consume a value, making sure the compiler doesn't optimize away the computation of this
 128      * value, even if it is otherwise unused.
 129      */
 130     @SuppressWarnings("unused")
 131     public static void blackhole(byte value) {
 132     }
 133 
 134     /**
 135      * Consume a value, making sure the compiler doesn't optimize away the computation of this
 136      * value, even if it is otherwise unused.
 137      */
 138     @SuppressWarnings("unused")
 139     public static void blackhole(short value) {
 140     }
 141 
 142     /**
 143      * Consume a value, making sure the compiler doesn't optimize away the computation of this
 144      * value, even if it is otherwise unused.
 145      */
 146     @SuppressWarnings("unused")
 147     public static void blackhole(char value) {
 148     }
 149 
 150     /**
 151      * Consume a value, making sure the compiler doesn't optimize away the computation of this
 152      * value, even if it is otherwise unused.
 153      */
 154     @SuppressWarnings("unused")
 155     public static void blackhole(int value) {
 156     }
 157 
 158     /**
 159      * Consume a value, making sure the compiler doesn't optimize away the computation of this
 160      * value, even if it is otherwise unused.
 161      */
 162     @SuppressWarnings("unused")
 163     public static void blackhole(long value) {
 164     }
 165 
 166     /**
 167      * Consume a value, making sure the compiler doesn't optimize away the computation of this
 168      * value, even if it is otherwise unused.
 169      */
 170     @SuppressWarnings("unused")
 171     public static void blackhole(float value) {
 172     }
 173 
 174     /**
 175      * Consume a value, making sure the compiler doesn't optimize away the computation of this
 176      * value, even if it is otherwise unused.
 177      */
 178     @SuppressWarnings("unused")
 179     public static void blackhole(double value) {
 180     }
 181 
 182     /**
 183      * Consume a value, making sure the compiler doesn't optimize away the computation of this
 184      * value, even if it is otherwise unused.
 185      */
 186     @SuppressWarnings("unused")
 187     public static void blackhole(Object value) {
 188     }
 189 
 190     /**
 191      * Forces a value to be kept in a register.
 192      */
 193     @SuppressWarnings("unused")
 194     public static void bindToRegister(boolean value) {
 195     }
 196 
 197     /**
 198      * Forces a value to be kept in a register.
 199      */
 200     @SuppressWarnings("unused")
 201     public static void bindToRegister(byte value) {
 202     }
 203 
 204     /**
 205      * Forces a value to be kept in a register.
 206      */
 207     @SuppressWarnings("unused")
 208     public static void bindToRegister(short value) {
 209     }
 210 
 211     /**
 212      * Forces a value to be kept in a register.
 213      */
 214     @SuppressWarnings("unused")
 215     public static void bindToRegister(char value) {
 216     }
 217 
 218     /**
 219      * Forces a value to be kept in a register.
 220      */
 221     @SuppressWarnings("unused")
 222     public static void bindToRegister(int value) {
 223     }
 224 
 225     /**
 226      * Forces a value to be kept in a register.
 227      */
 228     @SuppressWarnings("unused")
 229     public static void bindToRegister(long value) {
 230     }
 231 
 232     /**
 233      * Forces a value to be kept in a register.
 234      */
 235     @SuppressWarnings("unused")
 236     public static void bindToRegister(float value) {
 237     }
 238 
 239     /**
 240      * Forces a value to be kept in a register.
 241      */
 242     @SuppressWarnings("unused")
 243     public static void bindToRegister(double value) {
 244     }
 245 
 246     /**
 247      * Forces a value to be kept in a register.
 248      */
 249     @SuppressWarnings("unused")
 250     public static void bindToRegister(Object value) {
 251     }
 252 
 253     /**
 254      * Spills all caller saved registers.
 255      */
 256     public static void spillRegisters() {
 257     }
 258 
 259     /**
 260      * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
 261      *
 262      * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
 263      * opaque(3) will result in a real multiplication, because the compiler will not see that
 264      * opaque(3) is a constant.
 265      */
 266     public static boolean opaque(boolean value) {
 267         return value;
 268     }
 269 
 270     /**
 271      * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
 272      *
 273      * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
 274      * opaque(3) will result in a real multiplication, because the compiler will not see that
 275      * opaque(3) is a constant.
 276      */
 277     public static byte opaque(byte value) {
 278         return value;
 279     }
 280 
 281     /**
 282      * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
 283      *
 284      * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
 285      * opaque(3) will result in a real multiplication, because the compiler will not see that
 286      * opaque(3) is a constant.
 287      */
 288     public static short opaque(short value) {
 289         return value;
 290     }
 291 
 292     /**
 293      * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
 294      *
 295      * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
 296      * opaque(3) will result in a real multiplication, because the compiler will not see that
 297      * opaque(3) is a constant.
 298      */
 299     public static char opaque(char value) {
 300         return value;
 301     }
 302 
 303     /**
 304      * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
 305      *
 306      * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
 307      * opaque(3) will result in a real multiplication, because the compiler will not see that
 308      * opaque(3) is a constant.
 309      */
 310     public static int opaque(int value) {
 311         return value;
 312     }
 313 
 314     /**
 315      * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
 316      *
 317      * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
 318      * opaque(3) will result in a real multiplication, because the compiler will not see that
 319      * opaque(3) is a constant.
 320      */
 321     public static long opaque(long value) {
 322         return value;
 323     }
 324 
 325     /**
 326      * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
 327      *
 328      * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
 329      * opaque(3) will result in a real multiplication, because the compiler will not see that
 330      * opaque(3) is a constant.
 331      */
 332     public static float opaque(float value) {
 333         return value;
 334     }
 335 
 336     /**
 337      * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
 338      *
 339      * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
 340      * opaque(3) will result in a real multiplication, because the compiler will not see that
 341      * opaque(3) is a constant.
 342      */
 343     public static double opaque(double value) {
 344         return value;
 345     }
 346 
 347     /**
 348      * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
 349      *
 350      * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
 351      * opaque(3) will result in a real multiplication, because the compiler will not see that
 352      * opaque(3) is a constant.
 353      */
 354     public static <T> T opaque(T value) {
 355         return value;
 356     }
 357 
 358     public static <T> T guardingNonNull(T value) {
 359         if (value == null) {
 360             deoptimize();
 361         }
 362         return value;
 363     }
 364 
 365     /**
 366      * Ensures that the given object will be virtual (escape analyzed) at all points that are
 367      * dominated by the current position.
 368      */
 369     public static void ensureVirtualized(@SuppressWarnings("unused") Object object) {
 370     }
 371 
 372     /**
 373      * Ensures that the given object will be virtual at the current position.
 374      */
 375     public static void ensureVirtualizedHere(@SuppressWarnings("unused") Object object) {
 376     }
 377 }