Class CompilerDirectives

java.lang.Object
com.oracle.truffle.api.CompilerDirectives
public final class CompilerDirectives extends Object
Directives that influence the optimizations of the Truffle compiler. All of the operations have no effect when executed in the Truffle interpreter.
Since:
0.8 or earlier

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    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.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    FASTPATH_PROBABILITY
     
    static final double
    LIKELY_PROBABILITY
     
    static final double
    SLOWPATH_PROBABILITY
     
    static final double
    UNLIKELY_PROBABILITY
     

  • Method Summary

    Modifier and Type
    Method
    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(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 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 <T> T
    castExact(Object object, Class<T> clazz)
    Casts the given object to the exact class represented by clazz.
    static <T> T
    ensureAllocatedHere(T object)
    Prevents the compiler from moving an allocation, enabling precise OutOfMemoryError exception locations.
    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 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 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 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.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • LIKELY_PROBABILITY

      public static final double LIKELY_PROBABILITY
      Since:
      0.8 or earlier
      See Also:

    • UNLIKELY_PROBABILITY

      public static final double UNLIKELY_PROBABILITY
      Since:
      0.8 or earlier
      See Also:

    • SLOWPATH_PROBABILITY

      public static final double SLOWPATH_PROBABILITY
      Since:
      0.8 or earlier
      See Also:

    • FASTPATH_PROBABILITY

      public static final double FASTPATH_PROBABILITY
      Since:
      0.8 or earlier
      See Also:

  • 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.
      Since:
      0.8 or earlier

    • 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.
      Since:
      0.8 or earlier

    • 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.
      Since:
      0.8 or earlier

    • hasNextTier

      public 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. interpretation tier can be replaced by a first tier, a first tier by a second tier compilation).
      Returns:
      true when executed in the first tier Truffle compilation, false otherwise.
      Since:
      22.0.0

    • 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.
      Since:
      0.8 or earlier

    • inCompilationRoot

      public static boolean inCompilationRoot()
      Returns a boolean value indicating whether the method is executed in the root of a Truffle compilation.
      Returns:
      false when executed in the interpreter or in an inlined CallTarget, true when in non-inlined compiled code.
      Since:
      0.28 or earlier

    • isCompilationConstant

      public static boolean isCompilationConstant(Object value)
      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 return 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.
      Parameters:
      value -
      Returns:
      true when given value is seen as compilation constant, false if not compilation constant.
      Since:
      0.8 or earlier

    • isPartialEvaluationConstant

      public static boolean isPartialEvaluationConstant(Object value)
      Returns a boolean indicating whether a given value is seen as constant during the initial partial evaluation phase. If this method is called in the interpreter this method will always return true.

      Because of that one should consider if the code guarded by this check should be run in interpreter or not. If it's faster to not run the guarded code in interpreter one can use: 

      if (CompilerDirectives.inCompiledCode() && CompilerDirectives.isPartialEvaluationConstant(value)) {
    // logic only run in compiled code if value is a PE constant
}
      but beware that code is never run in interpreter and so might lead to subtle bugs and is harder to debug. If it does not matter much whether the code runs in interpreter it's best to just: 
      if (CompilerDirectives.isPartialEvaluationConstant(value)) {
    // logic run in interpreter and in compiled code if value is a PE constant
}
      Parameters:
      value -
      Returns:
      true when given value is seen as compilation constant or in interpreter, false otherwise.
      Since:
      0.8 or earlier

    • interpreterOnly

      public 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.
      Parameters:
      runnable - the closure that should only be executed in the interpreter
      Since:
      0.8 or earlier

    • interpreterOnly

      public static <T> T interpreterOnly(Callable<T> callable) throws Exception
      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.
      Since:
      0.8 or earlier

    • 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 (see LIKELY_PROBABILITY , UNLIKELY_PROBABILITY, SLOWPATH_PROBABILITY, FASTPATH_PROBABILITY ).
      Parameters:
      probability - the probability value between 0.0 and 1.0 that should be injected
      Since:
      0.8 or earlier

    • bailout

      public static void bailout(String reason)
      Bails out of a compilation (e.g., for guest language features that should never be compiled).
      Parameters:
      reason - the reason for the bailout
      Since:
      0.8 or earlier

    • materialize

      public 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.
      Parameters:
      obj - the object to exclude from Escape Analysis
      Since:
      0.8 or earlier

    • ensureAllocatedHere

      public static <T> T ensureAllocatedHere(T object)
      Prevents the compiler from moving an allocation, enabling precise OutOfMemoryError exception locations. This intrinsic ensures the allocation's immobility and guarantees that the compiler's optimizations do not eliminate the allocation. Imposing such a restriction can hinder certain compiler optimizations, potentially degrading performance. If the intrinsic does not find an allocation as its argument, it causes a runtime compilation failure, invoking bailout(String). Example usage: 
      int[] tryAllocateArray() {
    int[] array;
    try {
        array = CompilerDirectives.ensureAllocatedHere(new int[42]);
    } catch (OutOfMemoryError e) {
        // handle out of memory errors to maintain consistency
        array = null;
    }
    return array;
}
      Since:
      24.1.0

    • ensureVirtualized

      public 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.
      Since:
      0.8 or earlier

    • ensureVirtualizedHere

      public static void ensureVirtualizedHere(Object object)
      Ensures that the given object will be virtual at the current position.
      Since:
      0.8 or earlier

    • blackhole

      public 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. This should only be used for benchmarking purposes.
      Since:
      21.2

    • blackhole

      public 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. This should only be used for benchmarking purposes.
      Since:
      21.2

    • blackhole

      public 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. This should only be used for benchmarking purposes.
      Since:
      21.2

    • blackhole

      public 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. This should only be used for benchmarking purposes.
      Since:
      21.2

    • blackhole

      public 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. This should only be used for benchmarking purposes.
      Since:
      21.2

    • blackhole

      public 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. This should only be used for benchmarking purposes.
      Since:
      21.2

    • blackhole

      public 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. This should only be used for benchmarking purposes.
      Since:
      21.2

    • blackhole

      public 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. This should only be used for benchmarking purposes.
      Since:
      21.2

    • blackhole

      public 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. This should only be used for benchmarking purposes.
      Since:
      21.2

    • castExact

      public static <T> T castExact(Object object, Class<T> clazz)
      Casts the given object to the exact class represented by clazz. The cast succeeds only if object == null || object.getClass() == clazz and thus fails for any subclass.
      Parameters:
      object - the object to be cast
      clazz - the class to check against, must not be null
      Returns:
      the object after casting
      Throws:
      ClassCastException - if the object is non-null and not exactly of the given class
      NullPointerException - if the class argument is null
      Since:
      0.33
      See Also:

    • isExact

      public static boolean isExact(Object object, Class<?> clazz)
      Checks the given object to the exact class represented by clazz. The method returns true only if object != null && object.getClass() == clazz and thus fails for any subclass.
      Parameters:
      object - the object to be cast
      clazz - the class to check against, must not be null
      Throws:
      NullPointerException - if the class argument is null
      Since:
      21.1

    • shouldNotReachHere

      public static RuntimeException shouldNotReachHere()
      Indicates a code path that is not supposed to be reached during compilation or interpretation. Reaching this method is considered a fatal internal error and execution should not continue. Transfers to interpreter and 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();
}
      Since:
      20.2

    • shouldNotReachHere

      public static RuntimeException shouldNotReachHere(String message)
      Indicates a code path that is not supposed to be reached during compilation or interpretation. Reaching this method is considered a fatal internal error and execution should not continue. Transfers to interpreter and 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");
}
      Parameters:
      message - an additional message for the exception thrown.
      Since:
      20.2

    • shouldNotReachHere

      public static RuntimeException shouldNotReachHere(Throwable cause)
      Indicates a code path that is not supposed to be reached during compilation or interpretation. Reaching this method is considered a fatal internal error and execution should not continue. Transfers to interpreter and 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");
}
      Parameters:
      cause - the cause if an exception was responsible for the unexpected case.
      Since:
      20.2

    • shouldNotReachHere

      public static RuntimeException shouldNotReachHere(String message, Throwable cause)
      Indicates a code path that is not supposed to be reached during compilation or interpretation. Reaching this method is considered a fatal internal error and execution should not continue. Transfers to interpreter and 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");
}
      Parameters:
      message - an additional message for the exception thrown.
      cause - the cause if an exception was responsible for the unexpected case.
      Since:
      20.2