Class BytecodeFrame

java.lang.Object
com.oracle.truffle.api.bytecode.BytecodeFrame
public final class BytecodeFrame extends Object
Represents a captured Bytecode DSL frame, including the location metadata needed to access the data in the frame.

BytecodeFrame is intended for use cases where the frame escapes or outlives the root node invocation. Prefer using a built-in operation or LocalAccessor to access the frame whenever possible.

There are a few ways to capture the frame:

Copied frames do not observe updates made to the original frame.

Note: if the interpreter uses block scoping, any non-copied BytecodeFrame is only valid until the interpreter continues execution. The frame must not be used after this point; doing so can cause undefined behaviour. If you need to access the frame after execution continues, you should capture a copy or explicitly copy() the captured bytecode frame. This restriction also applies to frames created by methods like get(TruffleStackTraceElement), which do not specify whether they capture the original frame or a copy.

Since:
25.1

  • Method Details

    • copy

      public BytecodeFrame copy()
      Returns a copy of this frame. This method can be used to snapshot the current state of a bytecode frame, in case it may be modified or become invalid in the future.
      Returns:
      a copy of this frame that is always valid and will not observe updates
      Since:
      25.1

    • getLocation

      public BytecodeLocation getLocation()
      Returns the bytecode location associated with the captured frame. This location is only valid until the bytecode interpreter resumes execution.
      Since:
      25.1

    • getBytecodeNode

      public BytecodeNode getBytecodeNode()
      Returns the bytecode node associated with the captured frame.
      Since:
      25.1

    • getBytecodeIndex

      public int getBytecodeIndex()
      Returns the bytecode index associated with the captured frame.
      Since:
      25.1

    • getLocalCount

      public int getLocalCount()
      Returns the number of live locals in the captured frame.
      Since:
      25.1

    • getLocalValue

      public Object getLocalValue(int localOffset)
      Returns the value of the local at the given offset. The offset should be between 0 and getLocalCount().
      Since:
      25.1

    • setLocalValue

      public void setLocalValue(int localOffset, Object value)
      Updates the value of the local at the given offset. The offset should be between 0 and getLocalCount().

      This method will throw an AssertionError if the captured frame does not support writes.

      Since:
      25.1

    • getLocalNames

      public Object[] getLocalNames()
      Returns the names associated with the live locals, if provided.
      Since:
      25.1

    • getArgumentCount

      public int getArgumentCount()
      Returns the number of arguments in the captured frame.
      Since:
      25.1

    • getArgument

      public Object getArgument(int argumentIndex)
      Returns the value of the argument at the given index. The offset should be between 0 and getArgumentCount().
      Since:
      25.1

    • setArgument

      public void setArgument(int argumentIndex, Object value)
      Updates the value of the local at the given offset. The offset should be between 0 and getArgumentCount().
      Since:
      25.1

    • getFrameDescriptorInfo

      public Object getFrameDescriptorInfo()
      Returns the info object associated with the frame's descriptor.
      Since:
      25.1

    • get

      public static BytecodeFrame get(FrameInstance frameInstance, FrameInstance.FrameAccess access)
      Creates a bytecode frame from the given frame instance.
      Parameters:
      frameInstance - the frame instance
      access - the access mode to use when capturing the frame
      Returns:
      a bytecode frame, or null if the frame instance is missing location info.
      Since:
      25.1

    • getNonVirtual

      public static BytecodeFrame getNonVirtual(FrameInstance frameInstance)
      Attempts to create a bytecode frame from the given frame instance. Returns null if the corresponding frame is virtual. The frame can be read from, written to, and escaped.

      This method can be used to probe for a frame that can safely escape without forcing materialization. For example, if a language needs to capture local variables from a stack frame, it's often more efficient to use an existing non-virtual frame rather than create a copy of all variables.

      Parameters:
      frameInstance - the frame instance
      Returns:
      a bytecode frame or null if the frame is virtual or if the frame instance is missing location info.
      Since:
      25.1

    • get

      public static BytecodeFrame get(TruffleStackTraceElement element)
      Creates a bytecode frame from the given stack trace element.

      This method will return null unless the interpreter specifies GenerateBytecode.captureFramesForTrace(), which indicates whether frames should be captured.

      Parameters:
      element - the stack trace element
      Returns:
      a bytecode frame, or null if the frame was not captured or the stack trace element is missing location information.
      Since:
      25.1

    • getNonVirtual

      public static BytecodeFrame getNonVirtual(TruffleStackTraceElement element)
      Attempts to create a bytecode frame from the given stack trace element. Returns null if the corresponding frame is virtual. The frame can be read from, written to, and escaped.

      This method can be used to probe for a frame that can safely escape without forcing materialization. For example, if a language needs to capture local variables from a stack frame, it's often more efficient to use an existing non-virtual frame rather than create a copy of all variables.

      Parameters:
      element - the stack trace element
      Returns:
      a bytecode frame or null if the frame is virtual/unavailable or if the frame instance is missing location info.
      Since:
      25.1