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:

SuspendedEvent.getStackFrames(), SuspendedEvent.getTopStackFrame()

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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 Detail
  - 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:
    
    DebuggerSession.setShowHostStackFrames(boolean)
  - 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:
    
    DebugStackFrame.isHost()
  - 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

Class DebugStackFrame

Method Summary

Methods inherited from class java.lang.Object

Method Detail

isInternal

isHost

getHostTraceElement

getName

getSourceSection

getLanguage

getScope

getRawNode

getRawFrame

eval

equals

hashCode