001/*
002 * Copyright (c) 2015, 2015, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.
008 *
009 * This code is distributed in the hope that it will be useful, but WITHOUT
010 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
011 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
012 * version 2 for more details (a copy is included in the LICENSE file that
013 * accompanied this code).
014 *
015 * You should have received a copy of the GNU General Public License version
016 * 2 along with this work; if not, write to the Free Software Foundation,
017 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
018 *
019 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
020 * or visit www.oracle.com if you need additional information or have any
021 * questions.
022 */
023package com.oracle.graal.api.directives;
024
025// JaCoCo Exclude
026
027/**
028 * Directives that influence the compilation of methods by Graal. They don't influence the semantics
029 * of the code, but they are useful for unit testing and benchmarking.
030 */
031public final class GraalDirectives {
032
033    public static final double LIKELY_PROBABILITY = 0.75;
034    public static final double UNLIKELY_PROBABILITY = 1.0 - LIKELY_PROBABILITY;
035
036    public static final double SLOWPATH_PROBABILITY = 0.0001;
037    public static final double FASTPATH_PROBABILITY = 1.0 - SLOWPATH_PROBABILITY;
038
039    /**
040     * Directive for the compiler to fall back to the bytecode interpreter at this point.
041     */
042    public static void deoptimize() {
043    }
044
045    /**
046     * Directive for the compiler to fall back to the bytecode interpreter at this point, invalidate
047     * the compiled code and reprofile the method.
048     */
049    public static void deoptimizeAndInvalidate() {
050    }
051
052    /**
053     * Returns a boolean value indicating whether the method is executed in Graal-compiled code.
054     */
055    public static boolean inCompiledCode() {
056        return false;
057    }
058
059    /**
060     * A call to this method will never be duplicated by control flow optimizations in the compiler.
061     */
062    public static void controlFlowAnchor() {
063    }
064
065    /**
066     * Injects a probability for the given condition into the profiling information of a branch
067     * instruction. The probability must be a value between 0.0 and 1.0 (inclusive).
068     *
069     * Example usage (it specifies that the likelihood for a to be greater than b is 90%):
070     *
071     * <code>
072     * if (injectBranchProbability(0.9, a &gt; b)) {
073     *    // ...
074     * }
075     * </code>
076     *
077     * There are predefined constants for commonly used probabilities (see
078     * {@link #LIKELY_PROBABILITY} , {@link #UNLIKELY_PROBABILITY}, {@link #SLOWPATH_PROBABILITY},
079     * {@link #FASTPATH_PROBABILITY} ).
080     *
081     * @param probability the probability value between 0.0 and 1.0 that should be injected
082     */
083    public static boolean injectBranchProbability(double probability, boolean condition) {
084        assert probability >= 0.0 && probability <= 1.0;
085        return condition;
086    }
087
088    /**
089     * Injects an average iteration count of a loop into the probability information of a loop exit
090     * condition. The iteration count specifies how often the condition is checked, i.e. in for and
091     * while loops it is one more than the body iteration count, and in do-while loops it is equal
092     * to the body iteration count. The iteration count must be >= 1.0.
093     *
094     * Example usage (it specifies that the expected iteration count of the loop condition is 500,
095     * so the iteration count of the loop body is 499):
096     *
097     * <code>
098     * for (int i = 0; injectIterationCount(500, i < array.length); i++) {
099     *     // ...
100     * }
101     * </code>
102     *
103     * @param iterations the expected number of iterations that should be injected
104     */
105    public static boolean injectIterationCount(double iterations, boolean condition) {
106        return injectBranchProbability(1. - 1. / iterations, condition);
107    }
108
109    /**
110     * Consume a value, making sure the compiler doesn't optimize away the computation of this
111     * value, even if it is otherwise unused.
112     */
113    @SuppressWarnings("unused")
114    public static void blackhole(boolean value) {
115    }
116
117    /**
118     * Consume a value, making sure the compiler doesn't optimize away the computation of this
119     * value, even if it is otherwise unused.
120     */
121    @SuppressWarnings("unused")
122    public static void blackhole(byte value) {
123    }
124
125    /**
126     * Consume a value, making sure the compiler doesn't optimize away the computation of this
127     * value, even if it is otherwise unused.
128     */
129    @SuppressWarnings("unused")
130    public static void blackhole(short value) {
131    }
132
133    /**
134     * Consume a value, making sure the compiler doesn't optimize away the computation of this
135     * value, even if it is otherwise unused.
136     */
137    @SuppressWarnings("unused")
138    public static void blackhole(char value) {
139    }
140
141    /**
142     * Consume a value, making sure the compiler doesn't optimize away the computation of this
143     * value, even if it is otherwise unused.
144     */
145    @SuppressWarnings("unused")
146    public static void blackhole(int value) {
147    }
148
149    /**
150     * Consume a value, making sure the compiler doesn't optimize away the computation of this
151     * value, even if it is otherwise unused.
152     */
153    @SuppressWarnings("unused")
154    public static void blackhole(long value) {
155    }
156
157    /**
158     * Consume a value, making sure the compiler doesn't optimize away the computation of this
159     * value, even if it is otherwise unused.
160     */
161    @SuppressWarnings("unused")
162    public static void blackhole(float value) {
163    }
164
165    /**
166     * Consume a value, making sure the compiler doesn't optimize away the computation of this
167     * value, even if it is otherwise unused.
168     */
169    @SuppressWarnings("unused")
170    public static void blackhole(double value) {
171    }
172
173    /**
174     * Consume a value, making sure the compiler doesn't optimize away the computation of this
175     * value, even if it is otherwise unused.
176     */
177    @SuppressWarnings("unused")
178    public static void blackhole(Object value) {
179    }
180
181    /**
182     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
183     *
184     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
185     * opaque(3) will result in a real multiplication, because the compiler will not see that
186     * opaque(3) is a constant.
187     */
188    public static boolean opaque(boolean value) {
189        return value;
190    }
191
192    /**
193     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
194     *
195     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
196     * opaque(3) will result in a real multiplication, because the compiler will not see that
197     * opaque(3) is a constant.
198     */
199    public static byte opaque(byte value) {
200        return value;
201    }
202
203    /**
204     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
205     *
206     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
207     * opaque(3) will result in a real multiplication, because the compiler will not see that
208     * opaque(3) is a constant.
209     */
210    public static short opaque(short value) {
211        return value;
212    }
213
214    /**
215     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
216     *
217     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
218     * opaque(3) will result in a real multiplication, because the compiler will not see that
219     * opaque(3) is a constant.
220     */
221    public static char opaque(char value) {
222        return value;
223    }
224
225    /**
226     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
227     *
228     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
229     * opaque(3) will result in a real multiplication, because the compiler will not see that
230     * opaque(3) is a constant.
231     */
232    public static int opaque(int value) {
233        return value;
234    }
235
236    /**
237     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
238     *
239     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
240     * opaque(3) will result in a real multiplication, because the compiler will not see that
241     * opaque(3) is a constant.
242     */
243    public static long opaque(long value) {
244        return value;
245    }
246
247    /**
248     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
249     *
250     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
251     * opaque(3) will result in a real multiplication, because the compiler will not see that
252     * opaque(3) is a constant.
253     */
254    public static float opaque(float value) {
255        return value;
256    }
257
258    /**
259     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
260     *
261     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
262     * opaque(3) will result in a real multiplication, because the compiler will not see that
263     * opaque(3) is a constant.
264     */
265    public static double opaque(double value) {
266        return value;
267    }
268
269    /**
270     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
271     *
272     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
273     * opaque(3) will result in a real multiplication, because the compiler will not see that
274     * opaque(3) is a constant.
275     */
276    public static <T> T opaque(T value) {
277        return value;
278    }
279
280    public static <T> T guardingNonNull(T value) {
281        if (value == null) {
282            deoptimize();
283        }
284        return value;
285    }
286
287    /**
288     * Ensures that the given object will be virtual (escape analyzed) at all points that are
289     * dominated by the current position.
290     */
291    public static void ensureVirtualized(@SuppressWarnings("unused") Object object) {
292    }
293
294    /**
295     * Ensures that the given object will be virtual at the current position.
296     */
297    public static void ensureVirtualizedHere(@SuppressWarnings("unused") Object object) {
298    }
299}