Package com.oracle.truffle.api.debug

Class DebugStackFrame

java.lang.Object
com.oracle.truffle.api.debug.DebugStackFrame
public final class DebugStackFrame extends Object
Represents a frame in the guest language stack. A guest language stack frame consists of a name, the current source location and scopes containing local variables and arguments. Furthermore it allows to evaluate guest language expressions in the lexical context of a particular frame.

Debug stack frames are only valid as long as suspended events are valid. Suspended events are valid as long while the originating SuspendedCallback is still executing. All methods of the frame throw IllegalStateException if they become invalid.

Depending on the method, clients may access the stack frame only on the execution thread where the suspended event of the stack frame was created and the notification was received. For some methods, access from other threads may throw IllegalStateException. Please see the javadoc of the individual method for details.

Since:
0.17
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals(Object obj)
     
    DebugValue
    eval(String code)
    Evaluates the given code in the state of the current execution and in the same guest language as the current language is defined in.
    StackTraceElement
    getHostTraceElement()
    Provides a host frame.
    LanguageInfo
    getLanguage()
    Returns public information about the language of this frame.
    String
    getName()
    A description of the AST (expected to be a method or procedure name in most languages) that identifies the AST for the benefit of guest language programmers using tools; it might appear, for example in the context of a stack dump or trace and is not expected to be called often.
    Frame
    getRawFrame(Class<? extends TruffleLanguage<?>> languageClass, FrameInstance.FrameAccess access)
    Returns the underlying frame for this debug stack frame or null if the requesting language class does not match the root node guest language.
    Node
    getRawNode(Class<? extends TruffleLanguage<?>> languageClass)
    Returns the current node for this stack frame, or null if the requesting language class does not match the root node guest language.
    DebugScope
    getScope()
    Get the current inner-most scope.
    SourceSection
    getSourceSection()
    Returns the source section of the location where the debugging session was suspended.
    int
    hashCode()
     
    boolean
    isHost()
    Returns true if this frame is a host frame.
    boolean
    isInternal()
    Returns whether this stack frame is a language implementation artifact that should be hidden during normal guest language debugging, for example in stack traces.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • isInternal

      public boolean isInternal()
      Returns whether this stack frame is a language implementation artifact that should be hidden during normal guest language debugging, for example in stack traces.

      Language implementations sometimes create method calls internally that do not correspond to anything explicitly written by a programmer, for example when the body of a looping construct is implemented as callable block. Language implementors mark these methods as internal.

      Clients of the debugging API should assume that displaying internal frames is unlikely to help programmers debug guest language programs and might possibly create confusion. However, clients may choose to display all frames, for example in a special mode to support development of programming language implementations.

      The decision to mark a method as internal is language-specific, reflects judgments about tool usability, and is subject to change.

      This method is thread-safe.

      Since:
      0.17

    • isHost

      public boolean isHost()
      Returns true if this frame is a host frame. Host frames provide stack trace element, have no scope, no source section and can not evaluate code.

      Host frames are provided only when host info is set to true.

      Since:
      20.3
      See Also:

    • getHostTraceElement

      public StackTraceElement getHostTraceElement()
      Provides a host frame. Returns the host stack trace element if and only if this is host frame.
      Returns:
      the host stack trace element, or null when not a host frame.
      Since:
      20.3
      See Also:

    • getName

      public String getName() throws DebugException
      A description of the AST (expected to be a method or procedure name in most languages) that identifies the AST for the benefit of guest language programmers using tools; it might appear, for example in the context of a stack dump or trace and is not expected to be called often. If the language does not provide such a description then null is returned.

      This method is thread-safe.

      Throws:
      DebugException
      Since:
      0.17

    • getSourceSection

      public SourceSection getSourceSection()
      Returns the source section of the location where the debugging session was suspended. The source section is null if the source location is not available.

      This method is thread-safe.

      Since:
      0.17

    • getLanguage

      public LanguageInfo getLanguage()
      Returns public information about the language of this frame.
      Returns:
      the language info, or null when no language is associated with this frame.
      Since:
      19.0

    • getScope

      public DebugScope getScope() throws DebugException
      Get the current inner-most scope. The scope remain valid as long as the current stack frame remains valid.

      Use DebuggerSession.getTopScope(java.lang.String) to get scopes with global validity.

      This method is not thread-safe and will throw an IllegalStateException if called on another thread than it was created with.

      Returns:
      the scope, or null when no language is associated with this frame location, or when no local scope exists.
      Throws:
      DebugException - when guest language code throws an exception
      Since:
      0.26

    • getRawNode

      public Node getRawNode(Class<? extends TruffleLanguage<?>> languageClass)
      Returns the current node for this stack frame, or null if the requesting language class does not match the root node guest language. This method is permitted only if the guest language class is available. This is the case if you want to utilize the Debugger API directly from within a guest language, or if you are an instrument bound/dependent on a specific language.
      Parameters:
      languageClass - the Truffle language class for a given guest language
      Returns:
      the node associated with the frame
      Since:
      20.1

    • getRawFrame

      public Frame getRawFrame(Class<? extends TruffleLanguage<?>> languageClass, FrameInstance.FrameAccess access)
      Returns the underlying frame for this debug stack frame or null if the requesting language class does not match the root node guest language. This method is permitted only if the guest language class is available. This is the case if you want to utilize the Debugger API directly from within a guest language, or if you are an instrument bound/dependent on a specific language.
      Parameters:
      languageClass - the Truffle language class for a given guest language
      access - the frame access mode
      Returns:
      the frame
      Since:
      20.1

    • eval

      public DebugValue eval(String code) throws DebugException
      Evaluates the given code in the state of the current execution and in the same guest language as the current language is defined in. Returns a heap value that remains valid even if this stack frame becomes invalid.

      This method is not thread-safe and will throw an IllegalStateException if called on another thread than it was created with.

      Parameters:
      code - the code to evaluate
      Returns:
      the return value of the expression
      Throws:
      DebugException - when guest language code throws an exception
      IllegalStateException - if called on another thread than this frame was created with, or if language of this frame is not interactive.
      Since:
      0.17

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object
      Since:
      19.0

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
      Since:
      19.0