public final class CompilerDirectives extends Object
Modifier and Type | Class and Description |
---|---|
static interface |
CompilerDirectives.CompilationFinal
Marks fields that should be considered final for a Truffle compilation although they are not
final while executing in the interpreter.
|
static interface |
CompilerDirectives.TruffleBoundary
Marks a method that it is considered as a boundary for Truffle partial evaluation.
|
static interface |
CompilerDirectives.ValueType
Marks classes as value types.
|
Modifier and Type | Field and Description |
---|---|
static double |
FASTPATH_PROBABILITY |
static double |
LIKELY_PROBABILITY |
static double |
SLOWPATH_PROBABILITY |
static double |
UNLIKELY_PROBABILITY |
Modifier and Type | Method and Description |
---|---|
static void |
bailout(String reason)
Bails out of a compilation (e.g., for guest language features that should never be compiled).
|
static void |
blackhole(boolean value)
Consume a value, making sure the compiler doesn't optimize away the computation of this
value, even if it is otherwise unused.
|
static void |
blackhole(byte value)
Consume a value, making sure the compiler doesn't optimize away the computation of this
value, even if it is otherwise unused.
|
static void |
blackhole(char value)
Consume a value, making sure the compiler doesn't optimize away the computation of this
value, even if it is otherwise unused.
|
static void |
blackhole(double value)
Consume a value, making sure the compiler doesn't optimize away the computation of this
value, even if it is otherwise unused.
|
static void |
blackhole(float value)
Consume a value, making sure the compiler doesn't optimize away the computation of this
value, even if it is otherwise unused.
|
static void |
blackhole(int value)
Consume a value, making sure the compiler doesn't optimize away the computation of this
value, even if it is otherwise unused.
|
static void |
blackhole(long value)
Consume a value, making sure the compiler doesn't optimize away the computation of this
value, even if it is otherwise unused.
|
static void |
blackhole(Object value)
Consume a value, making sure the compiler doesn't optimize away the computation of this
value, even if it is otherwise unused.
|
static void |
blackhole(short value)
Consume a value, making sure the compiler doesn't optimize away the computation of this
value, even if it is otherwise unused.
|
static <T> T |
castExact(Object object,
Class<T> clazz)
Casts the given object to the exact class represented by
clazz . |
static void |
ensureVirtualized(Object object)
Ensures that the given object will be virtual (escape analyzed) at all points that are
dominated by the current position.
|
static void |
ensureVirtualizedHere(Object object)
Ensures that the given object will be virtual at the current position.
|
static boolean |
hasNextTier()
Returns a boolean value indicating whether the method is executed in a compilation tier which
can be replaced with a higher tier (e.g.
|
static boolean |
inCompilationRoot()
Returns a boolean value indicating whether the method is executed in the root of a Truffle
compilation.
|
static boolean |
inCompiledCode()
Returns a boolean value indicating whether the method is executed in the compiled code.
|
static boolean |
inInterpreter()
Returns a boolean value indicating whether the method is executed in the interpreter.
|
static boolean |
injectBranchProbability(double probability,
boolean condition)
Injects a probability for the given condition into the probability information of the
immediately succeeding branch instruction for the condition.
|
static <T> T |
interpreterOnly(Callable<T> callable)
Directive for the compiler that the given callable should only be executed in the
interpreter.
|
static void |
interpreterOnly(Runnable runnable)
Directive for the compiler that the given runnable should only be executed in the interpreter
and ignored in the compiled code.
|
static boolean |
isCompilationConstant(Object value)
Returns a boolean indicating whether or not a given value is seen as constant in optimized
code.
|
static boolean |
isExact(Object object,
Class<?> clazz)
Checks the given object to the exact class represented by
clazz . |
static boolean |
isPartialEvaluationConstant(Object value)
Returns a boolean indicating whether or not a given value is seen as constant during the
initial partial evaluation phase.
|
static void |
materialize(Object obj)
Ensures that the given object is not virtual, i.e., not removed by Escape Analysis at the
point of this call.
|
static RuntimeException |
shouldNotReachHere()
Indicates a code path that is not supposed to be reached during compilation or
interpretation.
|
static RuntimeException |
shouldNotReachHere(String message)
Indicates a code path that is not supposed to be reached during compilation or
interpretation.
|
static RuntimeException |
shouldNotReachHere(String message,
Throwable cause)
Indicates a code path that is not supposed to be reached during compilation or
interpretation.
|
static RuntimeException |
shouldNotReachHere(Throwable cause)
Indicates a code path that is not supposed to be reached during compilation or
interpretation.
|
static void |
transferToInterpreter()
Directive for the compiler to discontinue compilation at this code position and instead
insert a transfer to the interpreter.
|
static void |
transferToInterpreterAndInvalidate()
Directive for the compiler to discontinue compilation at this code position and instead
insert a transfer to the interpreter, invalidating the currently executing machine code.
|
public static final double LIKELY_PROBABILITY
public static final double UNLIKELY_PROBABILITY
public static final double SLOWPATH_PROBABILITY
public static final double FASTPATH_PROBABILITY
public static void transferToInterpreter()
public static void transferToInterpreterAndInvalidate()
public static boolean inInterpreter()
true
when executed in the interpreter, false
in compiled code.public static boolean hasNextTier()
true
when executed in the first tier Truffle compilation, false
otherwise.public static boolean inCompiledCode()
false
when executed in the interpreter, true
in compiled code.public static boolean inCompilationRoot()
false
when executed in the interpreter or in an inlined CallTarget
,
true
when in non-inlined compiled code.public static boolean isCompilationConstant(Object value)
true
.
Note that optimizations that a compiler will apply to code that is conditional on
isCompilationConstant
may be limited. For this reason
isCompilationConstant
is not recommended for use to select between alternate
implementations of functionality depending on whether a value is constant. Instead, it is
intended for use as a diagnostic mechanism.value
- true
when given value is seen as compilation constant, false
if not
compilation constant.public static boolean isPartialEvaluationConstant(Object value)
true
.value
- true
when given value is seen as compilation constant, false
if not
compilation constant.public static void interpreterOnly(Runnable runnable)
runnable
- the closure that should only be executed in the interpreterpublic static <T> T interpreterOnly(Callable<T> callable) throws Exception
callable
- the closure that should only be executed in the interpreterException
- If the closure throws an exception when executed in the interpreter.public static boolean injectBranchProbability(double probability, boolean condition)
if (injectBranchProbability(0.9, a > b)) {
// ...
}
Example usage for a combined condition (it specifies that the likelihood for a to be greater
than b is 90% and under the assumption that this is true, the likelihood for a being 0 is
10%):
if (injectBranchProbability(0.9, a > b) && injectBranchProbability(0.1, a == 0)) {
// ...
}
There are predefined constants for commonly used probabilities (see
CompilerDirectives.LIKELY_PROBABILITY
, CompilerDirectives.UNLIKELY_PROBABILITY
, CompilerDirectives.SLOWPATH_PROBABILITY
,
CompilerDirectives.FASTPATH_PROBABILITY
).probability
- the probability value between 0.0 and 1.0 that should be injectedpublic static void bailout(String reason)
reason
- the reason for the bailoutpublic static void materialize(Object obj)
obj
- the object to exclude from Escape Analysispublic static void ensureVirtualized(Object object)
public static void ensureVirtualizedHere(Object object)
public static void blackhole(boolean value)
public static void blackhole(byte value)
public static void blackhole(short value)
public static void blackhole(char value)
public static void blackhole(int value)
public static void blackhole(long value)
public static void blackhole(float value)
public static void blackhole(double value)
public static void blackhole(Object value)
public static <T> T castExact(Object object, Class<T> clazz)
clazz
. The cast succeeds
only if object == null || object.getClass() == clazz
and thus fails for any subclass.object
- the object to be castclazz
- the class to check against, must not be nullClassCastException
- if the object is non-null and not exactly of the given classNullPointerException
- if the class argument is nullClass.cast(Object)
public static boolean isExact(Object object, Class<?> clazz)
clazz
. The method returns
true
only if object != null && object.getClass() == clazz
and thus fails
for any subclass.object
- the object to be castclazz
- the class to check against, must not be nullNullPointerException
- if the class argument is nullpublic static RuntimeException shouldNotReachHere()
invalidates
the compiled code
and always throws an AssertionError
when invoked.
This method returns a runtime exception to be conveniently used in combination with Java throw statements, for example:
if (expectedCondition) { return 42; } else { throw shouldNotReachHere(); }
public static RuntimeException shouldNotReachHere(String message)
invalidates
the compiled code
and always throws an AssertionError
when invoked.
This method returns a runtime exception to be conveniently used in combination with Java throw statements, for example:
if (expectedCondition) { return 42; } else { throw shouldNotReachHere("Additional message"); }
message
- an additional message for the exception thrown.public static RuntimeException shouldNotReachHere(Throwable cause)
invalidates
the compiled code
and always throws an AssertionError
when invoked.
This method returns a runtime exception to be conveniently used in combination with Java throw statements, for example:
if (expectedCondition) { return 42; } else { throw shouldNotReachHere("Additional message"); }
cause
- the cause if an exception was responsible for the unexpected case.public static RuntimeException shouldNotReachHere(String message, Throwable cause)
invalidates
the compiled code
and always throws an AssertionError
when invoked.
This method returns a runtime exception to be conveniently used in combination with Java throw statements, for example:
if (expectedCondition) { return 42; } else { throw shouldNotReachHere("Additional message"); }
message
- an additional message for the exception thrown.cause
- the cause if an exception was responsible for the unexpected case.