Class CompilerDirectives


  • public final class CompilerDirectives
    extends java.lang.Object
    Directives that influence the optimizations of the Truffle compiler. All of the operations have no effect when executed in the Truffle interpreter.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void bailout​(java.lang.String reason)
      Bails out of a compilation (e.g., for guest language features that should never be compiled).
      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​(java.lang.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​(java.util.concurrent.Callable<T> callable)
      Directive for the compiler that the given callable should only be executed in the interpreter.
      static boolean isCompilationConstant​(java.lang.Object value)
      Returns a boolean indicating whether or not a given value is seen as constant in optimized code.
      static void materialize​(java.lang.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 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.
      static <T> T unsafeCast​(java.lang.Object value, java.lang.Class<T> type, boolean condition)
      Casts the given value to the value of the given type without any checks.
      static <T> T unsafeCast​(java.lang.Object value, java.lang.Class<T> type, boolean condition, boolean nonNull)
      Casts the given value to the value of the given type without any checks.
      static boolean unsafeGetBoolean​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to a boolean value within an object.
      static byte unsafeGetByte​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to a byte value within an object.
      static double unsafeGetDouble​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to a double value within an object.
      static boolean unsafeGetFinalBoolean​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to a final boolean value within an object.
      static byte unsafeGetFinalByte​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to a final byte value within an object.
      static double unsafeGetFinalDouble​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to a final double value within an object.
      static float unsafeGetFinalFloat​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to a final float value within an object.
      static int unsafeGetFinalInt​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to a final int value within an object.
      static long unsafeGetFinalLong​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to a final long value within an object.
      static java.lang.Object unsafeGetFinalObject​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to a final Object value within an object.
      static short unsafeGetFinalShort​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to a final short value within an object.
      static float unsafeGetFloat​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to a float value within an object.
      static int unsafeGetInt​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to an int value within an object.
      static long unsafeGetLong​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to a long value within an object.
      static java.lang.Object unsafeGetObject​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to an Object value within an object.
      static short unsafeGetShort​(java.lang.Object receiver, long offset, boolean condition, java.lang.Object locationIdentity)
      Unsafe access to a short value within an object.
      static void unsafePutBoolean​(java.lang.Object receiver, long offset, boolean value, java.lang.Object locationIdentity)
      Write a boolean value within an object.
      static void unsafePutByte​(java.lang.Object receiver, long offset, byte value, java.lang.Object locationIdentity)
      Write a byte value within an object.
      static void unsafePutDouble​(java.lang.Object receiver, long offset, double value, java.lang.Object locationIdentity)
      Write a double value within an object.
      static void unsafePutFloat​(java.lang.Object receiver, long offset, float value, java.lang.Object locationIdentity)
      Write a float value within an object.
      static void unsafePutInt​(java.lang.Object receiver, long offset, int value, java.lang.Object locationIdentity)
      Write an int value within an object.
      static void unsafePutLong​(java.lang.Object receiver, long offset, long value, java.lang.Object locationIdentity)
      Write a long value within an object.
      static void unsafePutObject​(java.lang.Object receiver, long offset, java.lang.Object value, java.lang.Object locationIdentity)
      Write an Object value within an object.
      static void unsafePutShort​(java.lang.Object receiver, long offset, short value, java.lang.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
    • Constructor Detail

      • CompilerDirectives

        public CompilerDirectives()
    • Method Detail

      • 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​(java.lang.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​(java.lang.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​(java.util.concurrent.Callable<T> callable)
                                     throws java.lang.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:
        java.lang.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​(java.lang.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​(java.lang.Object value,
                                       java.lang.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​(java.lang.Object value,
                                       java.lang.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​(java.lang.Object receiver,
                                               long offset,
                                               boolean condition,
                                               java.lang.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​(java.lang.Object receiver,
                                         long offset,
                                         boolean condition,
                                         java.lang.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​(java.lang.Object receiver,
                                           long offset,
                                           boolean condition,
                                           java.lang.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​(java.lang.Object receiver,
                                       long offset,
                                       boolean condition,
                                       java.lang.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​(java.lang.Object receiver,
                                         long offset,
                                         boolean condition,
                                         java.lang.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​(java.lang.Object receiver,
                                           long offset,
                                           boolean condition,
                                           java.lang.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​(java.lang.Object receiver,
                                             long offset,
                                             boolean condition,
                                             java.lang.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 java.lang.Object unsafeGetObject​(java.lang.Object receiver,
                                                       long offset,
                                                       boolean condition,
                                                       java.lang.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​(java.lang.Object receiver,
                                            long offset,
                                            boolean value,
                                            java.lang.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​(java.lang.Object receiver,
                                         long offset,
                                         byte value,
                                         java.lang.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​(java.lang.Object receiver,
                                          long offset,
                                          short value,
                                          java.lang.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​(java.lang.Object receiver,
                                        long offset,
                                        int value,
                                        java.lang.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​(java.lang.Object receiver,
                                         long offset,
                                         long value,
                                         java.lang.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​(java.lang.Object receiver,
                                          long offset,
                                          float value,
                                          java.lang.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​(java.lang.Object receiver,
                                           long offset,
                                           double value,
                                           java.lang.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​(java.lang.Object receiver,
                                           long offset,
                                           java.lang.Object value,
                                           java.lang.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​(java.lang.Object receiver,
                                                    long offset,
                                                    boolean condition,
                                                    java.lang.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​(java.lang.Object receiver,
                                              long offset,
                                              boolean condition,
                                              java.lang.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​(java.lang.Object receiver,
                                                long offset,
                                                boolean condition,
                                                java.lang.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​(java.lang.Object receiver,
                                            long offset,
                                            boolean condition,
                                            java.lang.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​(java.lang.Object receiver,
                                              long offset,
                                              boolean condition,
                                              java.lang.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​(java.lang.Object receiver,
                                                long offset,
                                                boolean condition,
                                                java.lang.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​(java.lang.Object receiver,
                                                  long offset,
                                                  boolean condition,
                                                  java.lang.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 java.lang.Object unsafeGetFinalObject​(java.lang.Object receiver,
                                                            long offset,
                                                            boolean condition,
                                                            java.lang.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​(java.lang.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