com.oracle.truffle.api.debug

Class DebugStackFrame

java.lang.Object

com.oracle.truffle.api.debug.DebugStackFrame

All Implemented Interfaces:

Iterable<DebugValue>

public final class DebugStackFrame
extends Object
implements Iterable<DebugValue>

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

Modifier and Type	Method and Description
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.
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.
DebugScope	getScope() Get the current inner-most scope.
SourceSection	getSourceSection() Returns the source section of the location where the debugging session was suspended.
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, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, iterator, spliterator

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

getName

public 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. If the language does not provide such a description then null is returned.

This method is thread-safe.

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

getScope

public DebugScope getScope()

Get the current inner-most scope. The scope remain valid as long as the current stack frame remains valid.

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

Since:

0.26

eval

public 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. 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

Since:

0.17