1/*
2 * Copyright (c) 2015, 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.
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 */
23package org.graalvm.compiler.api.directives;
24
25// JaCoCo Exclude
26
27/**
28 * Directives that influence the compilation of methods by Graal. They don't influence the semantics
29 * of the code, but they are useful for unit testing and benchmarking.
30 */
31public final class GraalDirectives {
32
33    public static final double LIKELY_PROBABILITY = 0.75;
34    public static final double UNLIKELY_PROBABILITY = 1.0 - LIKELY_PROBABILITY;
35
36    public static final double SLOWPATH_PROBABILITY = 0.0001;
37    public static final double FASTPATH_PROBABILITY = 1.0 - SLOWPATH_PROBABILITY;
38
39    /**
40     * Directive for the compiler to fall back to the bytecode interpreter at this point.
41     */
42    public static void deoptimize() {
43    }
44
45    /**
46     * Directive for the compiler to fall back to the bytecode interpreter at this point, invalidate
47     * the compiled code and reprofile the method.
48     */
49    public static void deoptimizeAndInvalidate() {
50    }
51
52    /**
53     * Returns a boolean value indicating whether the method is executed in Graal-compiled code.
54     */
55    public static boolean inCompiledCode() {
56        return false;
57    }
58
59    /**
60     * A call to this method will never be duplicated by control flow optimizations in the compiler.
61     */
62    public static void controlFlowAnchor() {
63    }
64
65    /**
66     * Injects a probability for the given condition into the profiling information of a branch
67     * instruction. The probability must be a value between 0.0 and 1.0 (inclusive).
68     *
69     * Example usage (it specifies that the likelihood for a to be greater than b is 90%):
70     *
71     * <code>
72     * if (injectBranchProbability(0.9, a &gt; b)) {
73     *    // ...
74     * }
75     * </code>
76     *
77     * There are predefined constants for commonly used probabilities (see
78     * {@link #LIKELY_PROBABILITY} , {@link #UNLIKELY_PROBABILITY}, {@link #SLOWPATH_PROBABILITY},
79     * {@link #FASTPATH_PROBABILITY} ).
80     *
81     * @param probability the probability value between 0.0 and 1.0 that should be injected
82     */
83    public static boolean injectBranchProbability(double probability, boolean condition) {
84        assert probability >= 0.0 && probability <= 1.0;
85        return condition;
86    }
87
88    /**
89     * Injects an average iteration count of a loop into the probability information of a loop exit
90     * condition. The iteration count specifies how often the condition is checked, i.e. in for and
91     * while loops it is one more than the body iteration count, and in do-while loops it is equal
92     * to the body iteration count. The iteration count must be >= 1.0.
93     *
94     * Example usage (it specifies that the expected iteration count of the loop condition is 500,
95     * so the iteration count of the loop body is 499):
96     *
97     * <code>
98     * for (int i = 0; injectIterationCount(500, i < array.length); i++) {
99     *     // ...
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     * Forces a value to be kept in a register.
183     */
184    @SuppressWarnings("unused")
185    public static void bindToRegister(boolean value) {
186    }
187
188    /**
189     * Forces a value to be kept in a register.
190     */
191    @SuppressWarnings("unused")
192    public static void bindToRegister(byte value) {
193    }
194
195    /**
196     * Forces a value to be kept in a register.
197     */
198    @SuppressWarnings("unused")
199    public static void bindToRegister(short value) {
200    }
201
202    /**
203     * Forces a value to be kept in a register.
204     */
205    @SuppressWarnings("unused")
206    public static void bindToRegister(char value) {
207    }
208
209    /**
210     * Forces a value to be kept in a register.
211     */
212    @SuppressWarnings("unused")
213    public static void bindToRegister(int value) {
214    }
215
216    /**
217     * Forces a value to be kept in a register.
218     */
219    @SuppressWarnings("unused")
220    public static void bindToRegister(long value) {
221    }
222
223    /**
224     * Forces a value to be kept in a register.
225     */
226    @SuppressWarnings("unused")
227    public static void bindToRegister(float value) {
228    }
229
230    /**
231     * Forces a value to be kept in a register.
232     */
233    @SuppressWarnings("unused")
234    public static void bindToRegister(double value) {
235    }
236
237    /**
238     * Forces a value to be kept in a register.
239     */
240    @SuppressWarnings("unused")
241    public static void bindToRegister(Object value) {
242    }
243
244    /**
245     * Spills all caller saved registers.
246     */
247    public static void spillRegisters() {
248    }
249
250    /**
251     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
252     *
253     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
254     * opaque(3) will result in a real multiplication, because the compiler will not see that
255     * opaque(3) is a constant.
256     */
257    public static boolean opaque(boolean value) {
258        return value;
259    }
260
261    /**
262     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
263     *
264     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
265     * opaque(3) will result in a real multiplication, because the compiler will not see that
266     * opaque(3) is a constant.
267     */
268    public static byte opaque(byte value) {
269        return value;
270    }
271
272    /**
273     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
274     *
275     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
276     * opaque(3) will result in a real multiplication, because the compiler will not see that
277     * opaque(3) is a constant.
278     */
279    public static short opaque(short value) {
280        return value;
281    }
282
283    /**
284     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
285     *
286     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
287     * opaque(3) will result in a real multiplication, because the compiler will not see that
288     * opaque(3) is a constant.
289     */
290    public static char opaque(char value) {
291        return value;
292    }
293
294    /**
295     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
296     *
297     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
298     * opaque(3) will result in a real multiplication, because the compiler will not see that
299     * opaque(3) is a constant.
300     */
301    public static int opaque(int value) {
302        return value;
303    }
304
305    /**
306     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
307     *
308     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
309     * opaque(3) will result in a real multiplication, because the compiler will not see that
310     * opaque(3) is a constant.
311     */
312    public static long opaque(long value) {
313        return value;
314    }
315
316    /**
317     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
318     *
319     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
320     * opaque(3) will result in a real multiplication, because the compiler will not see that
321     * opaque(3) is a constant.
322     */
323    public static float opaque(float value) {
324        return value;
325    }
326
327    /**
328     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
329     *
330     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
331     * opaque(3) will result in a real multiplication, because the compiler will not see that
332     * opaque(3) is a constant.
333     */
334    public static double opaque(double value) {
335        return value;
336    }
337
338    /**
339     * Do nothing, but also make sure the compiler doesn't do any optimizations across this call.
340     *
341     * For example, the compiler will constant fold the expression 5 * 3, but the expression 5 *
342     * opaque(3) will result in a real multiplication, because the compiler will not see that
343     * opaque(3) is a constant.
344     */
345    public static <T> T opaque(T value) {
346        return value;
347    }
348
349    public static <T> T guardingNonNull(T value) {
350        if (value == null) {
351            deoptimize();
352        }
353        return value;
354    }
355
356    /**
357     * Ensures that the given object will be virtual (escape analyzed) at all points that are
358     * dominated by the current position.
359     */
360    public static void ensureVirtualized(@SuppressWarnings("unused") Object object) {
361    }
362
363    /**
364     * Ensures that the given object will be virtual at the current position.
365     */
366    public static void ensureVirtualizedHere(@SuppressWarnings("unused") Object object) {
367    }
368}
369