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.
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @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

    Fields
    Modifier and Type
    Field
    Description
    static final double
     
    static final double
     
    static final double
     
    static final double
     
  • Constructor Summary

    Constructors
    Constructor
    Description
     
  • 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 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
    Directive for the compiler that the given runnable should only be executed in the interpreter and ignored in the compiled code.
    static <T> T
    Directive for the compiler that the given callable should only be executed in the interpreter.
    static boolean
    Returns a boolean indicating whether or not a given value is seen as constant in optimized code.
    static void
    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.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

  • 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

      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 false. This API may be used in combination with inCompiledCode() 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");
           }
         }
       }
       
       
      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, such as illustrated above.
      Parameters:
      value -
      Returns:
      true when given value is seen as compilation constant, false if not compilation constant.
    • 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
    • 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.
    • 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
    • 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
    • unsafeCast

      public 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. 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 type
      type - the specified new type of the value
      condition - 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

      public 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. 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 type
      type - the specified new type of the value
      condition - the condition that makes this cast safe also at an earlier location of the program
      nonNull - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 to
      offset - the offset at which to write to the object in bytes
      value - the value to be written
      locationIdentity - the location identity token that can be used for improved global value numbering or null
    • unsafePutByte

      public static void unsafePutByte(Object receiver, long offset, byte value, Object locationIdentity)
      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 to
      offset - the offset at which to write to the object in bytes
      value - the value to be written
      locationIdentity - 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 to
      offset - the offset at which to write to the object in bytes
      value - the value to be written
      locationIdentity - the location identity token that can be used for improved global value numbering or null
    • unsafePutInt

      public static void unsafePutInt(Object receiver, long offset, int value, Object locationIdentity)
      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 to
      offset - the offset at which to write to the object in bytes
      value - the value to be written
      locationIdentity - the location identity token that can be used for improved global value numbering or null
    • unsafePutLong

      public static void unsafePutLong(Object receiver, long offset, long value, Object locationIdentity)
      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 to
      offset - the offset at which to write to the object in bytes
      value - the value to be written
      locationIdentity - 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 to
      offset - the offset at which to write to the object in bytes
      value - the value to be written
      locationIdentity - 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 to
      offset - the offset at which to write to the object in bytes
      value - the value to be written
      locationIdentity - 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 to
      offset - the offset at which to write to the object in bytes
      value - the value to be written
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - 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 accessed
      offset - the offset at which to access the object in bytes
      condition - the condition that makes this access safe also at an earlier location in the program
      locationIdentity - the location identity token that can be used for improved global value numbering or null
      Returns:
      the accessed value
    • 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