Package com.oracle.truffle.api.frame

Interface Frame

All Known Subinterfaces:
MaterializedFrame, VirtualFrame
public interface Frame
Represents a frame containing values of local variables of the guest language. Instances of this type must not be stored in a field or cast to Object.
Since:
0.8 or earlier

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    clear(int slot)
    Clears the given indexed slot in the frame.
    default void
    clearObjectStatic(int slot)
    Clears the object value at the given slot in the frame.
    default void
    clearPrimitiveStatic(int slot)
    Clears the primitive value at the given slot in the frame.
    default void
    clearStatic(int slot)
    Clears the value at the given slot in the frame.
    default void
    copy(int srcSlot, int destSlot)
    Copies, including the type, from one slot to another.
    default void
    copyObjectStatic(int srcSlot, int destSlot)
    Copies an object value from one slot to another.
    default void
    copyPrimitiveStatic(int srcSlot, int destSlot)
    Copies a primitive value from one slot to another.
    default void
    copyStatic(int srcSlot, int destSlot)
    Copies from one slot to another.
    Object[]
    getArguments()
    Retrieves the arguments object from this frame.
    default Object
    getAuxiliarySlot(int slot)
     
    default boolean
    getBoolean(int slot)
    Read access to a local variable of type boolean.
    default boolean
    getBooleanStatic(int slot)
    Static read access to a local variable of type boolean.
    default byte
    getByte(int slot)
    Read access to a local variable of type byte.
    default byte
    getByteStatic(int slot)
    Static read access to a local variable of type byte.
    default double
    getDouble(int slot)
    Read access to a local variable of type double.
    default double
    getDoubleStatic(int slot)
    Static read access to a local variable of type double.
    default float
    getFloat(int slot)
    Read access to a local variable of type float.
    default float
    getFloatStatic(int slot)
    Static read access to a local variable of type float.
    FrameDescriptor
    getFrameDescriptor()
     
    default int
    getInt(int slot)
    Read access to a local variable of type int.
    default int
    getIntStatic(int slot)
    Static read access to a local variable of type int.
    default long
    getLong(int slot)
    Read access to a local variable of type long.
    default long
    getLongStatic(int slot)
    Static read access to a local variable of type long.
    default Object
    getObject(int slot)
    Read access to a local variable of type Object.
    default Object
    getObjectStatic(int slot)
    Static read access to a local variable of type Object.
    default byte
    getTag(int slot)
    Determines the actual FrameSlotKind of the value in the slot, and returns it as FrameSlotKind.tag.
    default Object
    getValue(int slot)
    Read access to a local variable of any type.
    default boolean
    isBoolean(int slot)
    Check whether the given indexed slot is of type boolean.
    default boolean
    isByte(int slot)
    Check whether the given indexed slot is of type byte.
    default boolean
    isDouble(int slot)
    Check whether the given indexed slot is of type double.
    default boolean
    isFloat(int slot)
    Check whether the given indexed slot is of type float.
    default boolean
    isInt(int slot)
    Check whether the given indexed slot is of type int.
    default boolean
    isLong(int slot)
    Check whether the given indexed slot is of type long.
    default boolean
    isObject(int slot)
    Check whether the given indexed slot is of type object.
    default boolean
    isStatic(int slot)
    Checks whether the given indexed slot is static.
    MaterializedFrame
    materialize()
    Materializes this frame, which allows it to be stored in a field or cast to Object.
    default void
    setAuxiliarySlot(int slot, Object value)
    Sets the value of the given auxiliary slot.
    default void
    setBoolean(int slot, boolean value)
    Write access to a local variable of type boolean.
    default void
    setBooleanStatic(int slot, boolean value)
    Static write access to a local variable of type boolean.
    default void
    setByte(int slot, byte value)
    Write access to a local variable of type byte.
    default void
    setByteStatic(int slot, byte value)
    Static write access to a local variable of type byte.
    default void
    setDouble(int slot, double value)
    Write access to a local variable of type double.
    default void
    setDoubleStatic(int slot, double value)
    Static write access to a local variable of type double.
    default void
    setFloat(int slot, float value)
    Write access to a local variable of type float.
    default void
    setFloatStatic(int slot, float value)
    Static write access to a local variable of type float.
    default void
    setInt(int slot, int value)
    Write access to a local variable of type int.
    default void
    setIntStatic(int slot, int value)
    Static write access to a local variable of type int.
    default void
    setLong(int slot, long value)
    Write access to a local variable of type long.
    default void
    setLongStatic(int slot, long value)
    Static write access to a local variable of type long.
    default void
    setObject(int slot, Object value)
    Write access to a local variable of type Object.
    default void
    setObjectStatic(int slot, Object value)
    Static write access to a local variable of type Object.
    default void
    swap(int first, int second)
    Swaps, including the type, the contents of two slots.
    default void
    swapObjectStatic(int first, int second)
    Swaps the object values of two slots.
    default void
    swapPrimitiveStatic(int first, int second)
    Swaps the primitive values of two slots.
    default void
    swapStatic(int first, int second)
    Swaps the contents of two slots.

  • Method Details

    • getFrameDescriptor

      FrameDescriptor getFrameDescriptor()
      Returns:
      the object describing the layout of this frame
      Since:
      0.8 or earlier

    • getArguments

      Object[] getArguments()
      Retrieves the arguments object from this frame. The runtime assumes that the arguments object is never null.
      Returns:
      the arguments used when calling this method
      Since:
      0.8 or earlier

    • materialize

      MaterializedFrame materialize()
      Materializes this frame, which allows it to be stored in a field or cast to Object.
      Returns:
      the new materialized frame
      Since:
      0.8 or earlier

    • getObject

      default Object getObject(int slot) throws FrameSlotTypeException
      Read access to a local variable of type Object.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable
      Throws:
      FrameSlotTypeException - if the current value is not of type object
      Since:
      22.0

    • setObject

      default void setObject(int slot, Object value)
      Write access to a local variable of type Object.
      Parameters:
      slot - the slot of the local variable
      value - the new value of the local variable
      Since:
      22.0

    • getByte

      default byte getByte(int slot) throws FrameSlotTypeException
      Read access to a local variable of type byte.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable
      Throws:
      FrameSlotTypeException
      Since:
      22.0

    • setByte

      default void setByte(int slot, byte value)
      Write access to a local variable of type byte.
      Parameters:
      slot - the slot of the local variable
      value - the new value of the local variable
      Since:
      22.0

    • getBoolean

      default boolean getBoolean(int slot) throws FrameSlotTypeException
      Read access to a local variable of type boolean.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable
      Throws:
      FrameSlotTypeException - if the current value is not of type boolean
      Since:
      22.0

    • setBoolean

      default void setBoolean(int slot, boolean value)
      Write access to a local variable of type boolean.
      Parameters:
      slot - the slot of the local variable
      value - the new value of the local variable
      Since:
      22.0

    • getInt

      default int getInt(int slot) throws FrameSlotTypeException
      Read access to a local variable of type int.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable
      Throws:
      FrameSlotTypeException - if the current value is not of type int
      Since:
      22.0

    • setInt

      default void setInt(int slot, int value)
      Write access to a local variable of type int.
      Parameters:
      slot - the slot of the local variable
      value - the new value of the local variable
      Since:
      22.0

    • getLong

      default long getLong(int slot) throws FrameSlotTypeException
      Read access to a local variable of type long.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable
      Throws:
      FrameSlotTypeException - if the current value is not of type long
      Since:
      22.0

    • setLong

      default void setLong(int slot, long value)
      Write access to a local variable of type long.
      Parameters:
      slot - the slot of the local variable
      value - the new value of the local variable
      Since:
      22.0

    • getFloat

      default float getFloat(int slot) throws FrameSlotTypeException
      Read access to a local variable of type float.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable
      Throws:
      FrameSlotTypeException - if the current value is not of type float
      Since:
      22.0

    • setFloat

      default void setFloat(int slot, float value)
      Write access to a local variable of type float.
      Parameters:
      slot - the slot of the local variable
      value - the new value of the local variable
      Since:
      22.0

    • getDouble

      default double getDouble(int slot) throws FrameSlotTypeException
      Read access to a local variable of type double.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable
      Throws:
      FrameSlotTypeException - if the current value is not of type double
      Since:
      22.0

    • setDouble

      default void setDouble(int slot, double value)
      Write access to a local variable of type double.
      Parameters:
      slot - the slot of the local variable
      value - the new value of the local variable
      Since:
      22.0

    • getValue

      default Object getValue(int slot)
      Read access to a local variable of any type.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable or defaultValue if unset
      Since:
      22.0

    • copy

      default void copy(int srcSlot, int destSlot)
      Copies, including the type, from one slot to another.
      Parameters:
      srcSlot - the slot of the source local variable
      destSlot - the slot of the target local variable
      Since:
      22.0

    • swap

      default void swap(int first, int second)
      Swaps, including the type, the contents of two slots.
      Parameters:
      first - the slot of the first local variable
      second - the slot of the second local variable
      Since:
      22.0

    • getTag

      default byte getTag(int slot)
      Determines the actual FrameSlotKind of the value in the slot, and returns it as FrameSlotKind.tag.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the tag of the value in the slot
      Since:
      22.0

    • isObject

      default boolean isObject(int slot)
      Check whether the given indexed slot is of type object.

      This method should not be used with static slots.

      Parameters:
      slot - the slot of the local variable
      Since:
      22.0

    • isByte

      default boolean isByte(int slot)
      Check whether the given indexed slot is of type byte.

      This method should not be used with static slots.

      Parameters:
      slot - the slot of the local variable
      Since:
      22.0

    • isBoolean

      default boolean isBoolean(int slot)
      Check whether the given indexed slot is of type boolean.

      This method should not be used with static slots.

      Parameters:
      slot - the slot of the local variable
      Since:
      22.0

    • isInt

      default boolean isInt(int slot)
      Check whether the given indexed slot is of type int.

      This method should not be used with static slots.

      Parameters:
      slot - the slot of the local variable
      Since:
      22.0

    • isLong

      default boolean isLong(int slot)
      Check whether the given indexed slot is of type long.

      This method should not be used with static slots.

      Parameters:
      slot - the slot of the local variable
      Since:
      22.0

    • isFloat

      default boolean isFloat(int slot)
      Check whether the given indexed slot is of type float.

      This method should not be used with static slots.

      Parameters:
      slot - the slot of the local variable
      Since:
      22.0

    • isDouble

      default boolean isDouble(int slot)
      Check whether the given indexed slot is of type double.

      This method should not be used with static slots.

      Parameters:
      slot - the slot of the local variable
      Since:
      22.0

    • isStatic

      default boolean isStatic(int slot)
      Checks whether the given indexed slot is static.

      This method should not be used with static slots.

      Parameters:
      slot - the slot of the local variable
      Since:
      22.2

    • clear

      default void clear(int slot)
      Clears the given indexed slot in the frame. Writing over a previously cleared slot is still allowed. Subsequent reads to this slot, unless re-written to, will fail with FrameSlotTypeException.

      This method is intended to be used for implementations of liveness analysis. As such, the compiler will find and report any inconsistency with respect to liveness analysis when using this method, such as clearing a slot in a branch, but not on another one, and their execution merge.

      Liveness analysis implementations are expected to clear unused slots on method entry

      Parameters:
      slot - the slot of the local variable
      Since:
      22.0

    • getAuxiliarySlot

      default Object getAuxiliarySlot(int slot)
      Parameters:
      slot - the auxiliary slot index to query
      Returns:
      the current value of the auxiliary slot - null if it was never set (not the frame descriptor's default value)
      Since:
      22.0

    • setAuxiliarySlot

      default void setAuxiliarySlot(int slot, Object value)
      Sets the value of the given auxiliary slot.
      Parameters:
      slot - the auxiliary slot index
      value - the new value
      Since:
      22.0

    • getObjectStatic

      default Object getObjectStatic(int slot)
      Static read access to a local variable of type Object. Requires the given slot to use FrameSlotKind.Static. Since this method does not perform any type checks, language implementations have to guarantee that the variable in the given slot is of type Object.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable, or null if slot is uninitialized.
      Since:
      22.2

    • setObjectStatic

      default void setObjectStatic(int slot, Object value)
      Static write access to a local variable of type Object. Requires the given slot to use FrameSlotKind.Static. Since this method does not update the internal slot type, language implementations have to track this information.
      Parameters:
      slot - the slot of the local variable
      value - the new value of the local variable
      Since:
      22.2

    • getByteStatic

      default byte getByteStatic(int slot)
      Static read access to a local variable of type byte. Requires the given slot to use FrameSlotKind.Static. Since this method does not perform any type checks, language implementations have to guarantee that the variable in the given slot is of type byte.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable, or 0 if slot is uninitialized.
      Since:
      22.2

    • setByteStatic

      default void setByteStatic(int slot, byte value)
      Static write access to a local variable of type byte. Requires the given slot to use FrameSlotKind.Static. Since this method does not update the internal slot type, language implementations have to track this information.
      Parameters:
      slot - the slot of the local variable
      value - the new value of the local variable
      Since:
      22.2

    • getBooleanStatic

      default boolean getBooleanStatic(int slot)
      Static read access to a local variable of type boolean. Requires the given slot to use FrameSlotKind.Static. Since this method does not perform any type checks, language implementations have to guarantee that the variable in the given slot is of type boolean.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable, or false if slot is uninitialized.
      Since:
      22.2

    • setBooleanStatic

      default void setBooleanStatic(int slot, boolean value)
      Static write access to a local variable of type boolean. Requires the given slot to use FrameSlotKind.Static. Since this method does not update the internal slot type, language implementations have to track this information.
      Parameters:
      slot - the slot of the local variable
      value - the new value of the local variable
      Since:
      22.2

    • getIntStatic

      default int getIntStatic(int slot)
      Static read access to a local variable of type int. Requires the given slot to use FrameSlotKind.Static. Since this method does not perform any type checks, language implementations have to guarantee that the variable in the given slot can is of type int.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable, or 0 if slot is uninitialized.
      Since:
      22.2

    • setIntStatic

      default void setIntStatic(int slot, int value)
      Static write access to a local variable of type int. Requires the given slot to use FrameSlotKind.Static. Since this method does not update the internal slot type, language implementations have to track this information.
      Parameters:
      slot - the slot of the local variable
      value - the new value of the local variable
      Since:
      22.2

    • getLongStatic

      default long getLongStatic(int slot)
      Static read access to a local variable of type long. Requires the given slot to use FrameSlotKind.Static. Since this method does not perform any type checks, language implementations have to guarantee that the variable in the given slot is of type long.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable, or 0 if slot is uninitialized.
      Since:
      22.2

    • setLongStatic

      default void setLongStatic(int slot, long value)
      Static write access to a local variable of type long. Requires the given slot to use FrameSlotKind.Static. Since this method does not update the internal slot type, language implementations have to track this information.
      Parameters:
      slot - the slot of the local variable
      value - the new value of the local variable
      Since:
      22.2

    • getFloatStatic

      default float getFloatStatic(int slot)
      Static read access to a local variable of type float. Requires the given slot to use FrameSlotKind.Static. Since this method does not perform any type checks, language implementations have to guarantee that the variable in the given slot is of type float.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable, or 0 if slot is uninitialized.
      Since:
      22.2

    • setFloatStatic

      default void setFloatStatic(int slot, float value)
      Static write access to a local variable of type float. Requires the given slot to use FrameSlotKind.Static. Since this method does not update the internal slot type, language implementations have to track this information.
      Parameters:
      slot - the slot of the local variable
      value - the new value of the local variable
      Since:
      22.2

    • getDoubleStatic

      default double getDoubleStatic(int slot)
      Static read access to a local variable of type double. Requires the given slot to use FrameSlotKind.Static. Since this method does not perform any type checks, language implementations have to guarantee that the variable in the given slot is of type double.
      Parameters:
      slot - the slot of the local variable
      Returns:
      the current value of the local variable, or 0 if slot is uninitialized.
      Since:
      22.2

    • setDoubleStatic

      default void setDoubleStatic(int slot, double value)
      Static write access to a local variable of type double. Requires the given slot to use FrameSlotKind.Static. Since this method does not update the internal slot type, language implementations have to track this information.
      Parameters:
      slot - the slot of the local variable
      value - the new value of the local variable
      Since:
      22.2

    • copyPrimitiveStatic

      default void copyPrimitiveStatic(int srcSlot, int destSlot)
      Copies a primitive value from one slot to another. Requires both slots to use FrameSlotKind.Static. Since this method does not perform any type checks, language implementations have to guarantee that the variable at the source slot is a primitive value.
      Parameters:
      srcSlot - the slot of the source local variable
      destSlot - the slot of the target local variable
      Since:
      22.2

    • copyObjectStatic

      default void copyObjectStatic(int srcSlot, int destSlot)
      Copies an object value from one slot to another. Requires both slots to use FrameSlotKind.Static. Since this method does not perform any type checks, language implementations have to guarantee that the variable at the source slot is an Object.
      Parameters:
      srcSlot - the slot of the source local variable
      destSlot - the slot of the target local variable
      Since:
      22.2

    • copyStatic

      default void copyStatic(int srcSlot, int destSlot)
      Copies from one slot to another. Requires both slots to use FrameSlotKind.Static. In cases where the underlying slot type is known, copyPrimitiveStatic(int, int) and copyObjectStatic(int, int) should be used for performance reasons.
      Parameters:
      srcSlot - the slot of the source local variable
      destSlot - the slot of the target local variable
      Since:
      22.3

    • swapPrimitiveStatic

      default void swapPrimitiveStatic(int first, int second)
      Swaps the primitive values of two slots. Requires both slots to use FrameSlotKind.Static. Since this method does not perform any type checks, language implementations have to guarantee that the variables in both slots are primitive values.
      Parameters:
      first - the slot of the first local variable
      second - the slot of the second local variable
      Since:
      22.3

    • swapObjectStatic

      default void swapObjectStatic(int first, int second)
      Swaps the object values of two slots. Requires both slots to use FrameSlotKind.Static. Since this method does not perform any type checks, language implementations have to guarantee that the variables in both slots are Objects.
      Parameters:
      first - the slot of the first local variable
      second - the slot of the second local variable
      Since:
      22.3

    • swapStatic

      default void swapStatic(int first, int second)
      Swaps the contents of two slots. Requires both slots to use FrameSlotKind.Static. In cases where the underlying slot type is known, swapPrimitiveStatic(int, int) and swapObjectStatic(int, int) should be used for performance reasons.
      Parameters:
      first - the slot of the first local variable
      second - the slot of the second local variable
      Since:
      22.3

    • clearPrimitiveStatic

      default void clearPrimitiveStatic(int slot)
      Clears the primitive value at the given slot in the frame. Requires the given slot to use FrameSlotKind.Static. Writing over a previously cleared slot is still allowed. Subsequent reads to the slot, unless re-written to, are not allowed and will fail with an AssertionError if assertions are enabled. Since this method does not perform any type checks, language implementations have to guarantee that the variable at the given slot is a primitive value.

      This method is intended to be used for implementations of liveness analysis. As such, the compiler will find and report any inconsistency with respect to liveness analysis when using this method, such as clearing a slot in a branch, but not on another one, and their execution merge.

      Liveness analysis implementations are expected to clear unused slots on method entry.
      Parameters:
      slot - the slot of the local variable
      Since:
      22.2

    • clearObjectStatic

      default void clearObjectStatic(int slot)
      Clears the object value at the given slot in the frame. Requires the given slot to use FrameSlotKind.Static. Writing over a previously cleared slot is still allowed. Subsequent reads to the slot, unless re-written to, are not allowed and will fail with an AssertionError if assertions are enabled. Since this method does not perform any type checks, language implementations have to guarantee that the variable at the given slot is an Object.

      This method is intended to be used for implementations of liveness analysis. As such, the compiler will find and report any inconsistency with respect to liveness analysis when using this method, such as clearing a slot in a branch, but not on another one, and their execution merge.

      Liveness analysis implementations are expected to clear unused slots on method entry.
      Parameters:
      slot - the slot of the local variable
      Since:
      22.2

    • clearStatic

      default void clearStatic(int slot)
      Clears the value at the given slot in the frame. Requires the given slot to use FrameSlotKind.Static. Writing over a previously cleared slot is still allowed. Subsequent reads to the slot, unless re-written to, are not allowed and will fail with an AssertionError if assertions are enabled. In cases where the underlying slot type is known, clearPrimitiveStatic(int) and clearObjectStatic(int) should be used for performance reasons.
      Parameters:
      slot - The slot of the local variable
      Since:
      22.3