Package com.oracle.truffle.api

Interface Assumption

public interface Assumption
An assumption is a global boolean flag that starts with the value true (i.e., the assumption is valid) and can subsequently be invalidated (using invalidate()). Once invalidated, an assumption can never get valid again. Assumptions can be created using the TruffleRuntime.createAssumption() or the TruffleRuntime.createAssumption(String) method. The Truffle compiler has special knowledge of this class in order to produce efficient machine code for checking an assumption in case the assumption object is a compile time constant. Therefore, assumptions should be stored in final fields in Truffle nodes. All instances of classes implementing Assumption must be held in final fields for compiler optimizations to take effect.

Do not manually subclass the Assumption interface. This class is only intended to be subclassed by Truffle runtime implementations to avoid polymorphism in performance sensitive methods.

Since:
0.8 or earlier

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Assumption
    ALWAYS_VALID
    An assumption that is always valid and fails with an UnsupportedOperationException if invalidated.
    static final Assumption
    NEVER_VALID
    An assumption that is never valid.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    check()
    Checks that this assumption is still valid.
    static Assumption
    create()
    Creates a new assumption with a name.
    static Assumption
    create(String name)
    Creates a new assumption with a name.
    String
    getName()
    A name for the assumption that is used for debug output.
    void
    invalidate()
    Invalidates this assumption.
    default void
    invalidate(String message)
    Invalidates this assumption.
    boolean
    isValid()
    Checks whether the assumption is still valid.
    static boolean
    isValidAssumption(Assumption assumption)
    Checks whether an assumption is not null and valid.
    static boolean
    isValidAssumption(Assumption[] assumptions)
    Checks whether all assumptions in an array are not null and valid.

  • Field Details

    • ALWAYS_VALID

      static final Assumption ALWAYS_VALID
      An assumption that is always valid and fails with an UnsupportedOperationException if invalidated.
      Since:
      22.1

    • NEVER_VALID

      static final Assumption NEVER_VALID
      An assumption that is never valid.
      Since:
      22.1

  • Method Details

    • check

      void check() throws InvalidAssumptionException
      Checks that this assumption is still valid. The method throws an exception, if this is no longer the case. This method is preferred over the isValid() method when writing guest language interpreter code. The catch block should perform a node rewrite (see Node.replace(Node)) with a node that no longer relies on the assumption.
      Throws:
      InvalidAssumptionException - If the assumption is no longer valid.
      Since:
      0.8 or earlier

    • isValid

      boolean isValid()
      Checks whether the assumption is still valid.
      Returns:
      a boolean value indicating the validity of the assumption
      Since:
      0.8 or earlier

    • invalidate

      void invalidate()
      Invalidates this assumption. Performs no operation, if the assumption is already invalid.
      Since:
      0.8 or earlier

    • invalidate

      default void invalidate(String message)
      Invalidates this assumption. Performs no operation, if the assumption is already invalid.
      Parameters:
      message - a message stating the reason of the invalidation
      Since:
      0.33

    • getName

      String getName()
      A name for the assumption that is used for debug output.
      Returns:
      the name of the assumption
      Since:
      0.8 or earlier

    • isValidAssumption

      static boolean isValidAssumption(Assumption assumption)
      Checks whether an assumption is not null and valid.
      Since:
      19.0

    • isValidAssumption

      static boolean isValidAssumption(Assumption[] assumptions)
      Checks whether all assumptions in an array are not null and valid. Returns false if the assumptions array itself is null. This method is designed for compilation. Note that the provided assumptions array must be a compilation final array with dimensions set to one.
      Since:
      19.0

    • create

      static Assumption create()
      Creates a new assumption with a name. Shortcut for TruffleRuntime.createAssumption().
      Since:
      22.1

    • create

      static Assumption create(String name)
      Creates a new assumption with a name. Shortcut for TruffleRuntime.createAssumption(String).
      Since:
      22.1