Package com.oracle.truffle.api
Class CompilerDirectives
java.lang.Object
com.oracle.truffle.api.CompilerDirectives
Directives that influence the optimizations of the Truffle compiler. All of the operations have
no effect when executed in the Truffle interpreter.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic @interface
Marks fields that should be considered final for a Truffle compilation although they are not final while executing in the interpreter.static @interface
Marks a method that it is considered as a boundary for Truffle partial evaluation.static @interface
Marks classes as value types. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final double
static final double
static final double
static final double
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic void
Bails out of a compilation (e.g., for guest language features that should never be compiled).static boolean
Returns a boolean value indicating whether the method is executed in the compiled code.static boolean
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 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 <T> T
interpreterOnly
(Callable<T> callable) Directive for the compiler that the given callable should only be executed in the interpreter.static boolean
isCompilationConstant
(Object value) Returns a boolean indicating whether or not a given value is seen as constant in optimized code.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 void
Directive for the compiler to discontinue compilation at this code position and instead insert a transfer to the interpreter.static void
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.static <T> T
unsafeCast
(Object value, Class<T> type, boolean condition) Casts the given value to the value of the given type without any checks.static <T> T
unsafeCast
(Object value, Class<T> type, boolean condition, boolean nonNull) Casts the given value to the value of the given type without any checks.static boolean
unsafeGetBoolean
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a boolean value within an object.static byte
unsafeGetByte
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a byte value within an object.static double
unsafeGetDouble
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a double value within an object.static boolean
unsafeGetFinalBoolean
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final boolean value within an object.static byte
unsafeGetFinalByte
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final byte value within an object.static double
unsafeGetFinalDouble
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final double value within an object.static float
unsafeGetFinalFloat
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final float value within an object.static int
unsafeGetFinalInt
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final int value within an object.static long
unsafeGetFinalLong
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final long value within an object.static Object
unsafeGetFinalObject
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final Object value within an object.static short
unsafeGetFinalShort
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final short value within an object.static float
unsafeGetFloat
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a float value within an object.static int
unsafeGetInt
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to an int value within an object.static long
unsafeGetLong
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a long value within an object.static Object
unsafeGetObject
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to an Object value within an object.static short
unsafeGetShort
(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a short value within an object.static void
unsafePutBoolean
(Object receiver, long offset, boolean value, Object locationIdentity) Write a boolean value within an object.static void
unsafePutByte
(Object receiver, long offset, byte value, Object locationIdentity) Write a byte value within an object.static void
unsafePutDouble
(Object receiver, long offset, double value, Object locationIdentity) Write a double value within an object.static void
unsafePutFloat
(Object receiver, long offset, float value, Object locationIdentity) Write a float value within an object.static void
unsafePutInt
(Object receiver, long offset, int value, Object locationIdentity) Write an int value within an object.static void
unsafePutLong
(Object receiver, long offset, long value, Object locationIdentity) Write a long value within an object.static void
unsafePutObject
(Object receiver, long offset, Object value, Object locationIdentity) Write an Object value within an object.static void
unsafePutShort
(Object receiver, long offset, short value, Object locationIdentity) Write a short value within an object.
-
Field Details
-
LIKELY_PROBABILITY
public static final double LIKELY_PROBABILITY- See Also:
-
UNLIKELY_PROBABILITY
public static final double UNLIKELY_PROBABILITY- See Also:
-
SLOWPATH_PROBABILITY
public static final double SLOWPATH_PROBABILITY- See Also:
-
FASTPATH_PROBABILITY
public static final double FASTPATH_PROBABILITY- See Also:
-
-
Constructor Details
-
CompilerDirectives
public CompilerDirectives()
-
-
Method Details
-
transferToInterpreter
public static void transferToInterpreter()Directive for the compiler to discontinue compilation at this code position and instead insert a transfer to the interpreter. -
transferToInterpreterAndInvalidate
public 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. -
inInterpreter
public static boolean inInterpreter()Returns a boolean value indicating whether the method is executed in the interpreter.- Returns:
true
when executed in the interpreter,false
in compiled code.
-
inCompiledCode
public static boolean inCompiledCode()Returns a boolean value indicating whether the method is executed in the compiled code.- Returns:
false
when executed in the interpreter,true
in compiled code.
-
isCompilationConstant
Returns a boolean indicating whether or not a given value is seen as constant in optimized code. If this method is called in the interpreter this method will always returnfalse
. This API may be used in combination withinCompiledCode()
to implement compilation constant assertions in the following way:void assertCompilationConstant(Object value) { if (inCompiledCode()) { if (!isCompilationConstant(value)) { throw new AssertionError("Given value is not constant"); } } }
isCompilationConstant
may be limited. For this reasonisCompilationConstant
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, such as illustrated above.- Parameters:
value
-- Returns:
true
when given value is seen as compilation constant,false
if not compilation constant.
-
interpreterOnly
Directive for the compiler that the given runnable should only be executed in the interpreter and ignored in the compiled code.- Parameters:
runnable
- the closure that should only be executed in the interpreter
-
interpreterOnly
Directive for the compiler that the given callable should only be executed in the interpreter.- Parameters:
callable
- the closure that should only be executed in the interpreter- Returns:
- the result of executing the closure in the interpreter and null in the compiled code
- Throws:
Exception
- If the closure throws an exception when executed in the interpreter.
-
injectBranchProbability
public 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. The probability must be a value between 0.0 and 1.0 (inclusive). The condition should not be a combined condition. Example usage immediately before an if statement (it specifies that the likelihood for a to be greater than b is 90%):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 (seeLIKELY_PROBABILITY
,UNLIKELY_PROBABILITY
,SLOWPATH_PROBABILITY
,FASTPATH_PROBABILITY
).- Parameters:
probability
- the probability value between 0.0 and 1.0 that should be injected
-
bailout
Bails out of a compilation (e.g., for guest language features that should never be compiled).- Parameters:
reason
- the reason for the bailout
-
unsafeCast
Casts the given value to the value of the given type without any checks. The class must evaluate to a constant. The condition parameter gives a hint to the compiler under which circumstances this cast can be moved to an earlier location in the program.- Parameters:
value
- the value that is known to have the specified typetype
- the specified new type of the valuecondition
- the condition that makes this cast safe also at an earlier location of the program- Returns:
- the value to be casted to the new type
-
unsafeCast
Casts the given value to the value of the given type without any checks. The class must evaluate to a constant. The condition parameter gives a hint to the compiler under which circumstances this cast can be moved to an earlier location in the program.- Parameters:
value
- the value that is known to have the specified typetype
- the specified new type of the valuecondition
- the condition that makes this cast safe also at an earlier location of the programnonNull
- whether value is known to never be null- Returns:
- the value to be casted to the new type
-
unsafeGetBoolean
public static boolean unsafeGetBoolean(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a boolean value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafeGetByte
public static byte unsafeGetByte(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a byte value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafeGetShort
public static short unsafeGetShort(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a short value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafeGetInt
public static int unsafeGetInt(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to an int value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafeGetLong
public static long unsafeGetLong(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a long value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafeGetFloat
public static float unsafeGetFloat(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a float value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafeGetDouble
public static double unsafeGetDouble(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a double value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafeGetObject
public static Object unsafeGetObject(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to an Object value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafePutBoolean
public static void unsafePutBoolean(Object receiver, long offset, boolean value, Object locationIdentity) Write a boolean value within an object. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is written tooffset
- the offset at which to write to the object in bytesvalue
- the value to be writtenlocationIdentity
- the location identity token that can be used for improved global value numbering or null
-
unsafePutByte
Write a byte value within an object. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is written tooffset
- the offset at which to write to the object in bytesvalue
- the value to be writtenlocationIdentity
- the location identity token that can be used for improved global value numbering or null
-
unsafePutShort
public static void unsafePutShort(Object receiver, long offset, short value, Object locationIdentity) Write a short value within an object. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is written tooffset
- the offset at which to write to the object in bytesvalue
- the value to be writtenlocationIdentity
- the location identity token that can be used for improved global value numbering or null
-
unsafePutInt
Write an int value within an object. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is written tooffset
- the offset at which to write to the object in bytesvalue
- the value to be writtenlocationIdentity
- the location identity token that can be used for improved global value numbering or null
-
unsafePutLong
Write a long value within an object. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is written tooffset
- the offset at which to write to the object in bytesvalue
- the value to be writtenlocationIdentity
- the location identity token that can be used for improved global value numbering or null
-
unsafePutFloat
public static void unsafePutFloat(Object receiver, long offset, float value, Object locationIdentity) Write a float value within an object. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is written tooffset
- the offset at which to write to the object in bytesvalue
- the value to be writtenlocationIdentity
- the location identity token that can be used for improved global value numbering or null
-
unsafePutDouble
public static void unsafePutDouble(Object receiver, long offset, double value, Object locationIdentity) Write a double value within an object. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is written tooffset
- the offset at which to write to the object in bytesvalue
- the value to be writtenlocationIdentity
- the location identity token that can be used for improved global value numbering or null
-
unsafePutObject
public static void unsafePutObject(Object receiver, long offset, Object value, Object locationIdentity) Write an Object value within an object. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is written tooffset
- the offset at which to write to the object in bytesvalue
- the value to be writtenlocationIdentity
- the location identity token that can be used for improved global value numbering or null
-
unsafeGetFinalBoolean
public static boolean unsafeGetFinalBoolean(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final boolean value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafeGetFinalByte
public static byte unsafeGetFinalByte(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final byte value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafeGetFinalShort
public static short unsafeGetFinalShort(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final short value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafeGetFinalInt
public static int unsafeGetFinalInt(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final int value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafeGetFinalLong
public static long unsafeGetFinalLong(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final long value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafeGetFinalFloat
public static float unsafeGetFinalFloat(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final float value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafeGetFinalDouble
public static double unsafeGetFinalDouble(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final double value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
unsafeGetFinalObject
public static Object unsafeGetFinalObject(Object receiver, long offset, boolean condition, Object locationIdentity) Unsafe access to a final Object value within an object. The condition parameter gives a hint to the compiler under which circumstances this access can be moved to an earlier location in the program. The location identity gives a hint to the compiler for improved global value numbering.- Parameters:
receiver
- the object that is accessedoffset
- the offset at which to access the object in bytescondition
- the condition that makes this access safe also at an earlier location in the programlocationIdentity
- the location identity token that can be used for improved global value numbering or null- Returns:
- the accessed value
-
materialize
Ensures that the given object is not virtual, i.e., not removed by Escape Analysis at the point of this call.- Parameters:
obj
- the object to exclude from Escape Analysis
-