Package com.oracle.truffle.api.debug

package com.oracle.truffle.api.debug

The debug package contains a debugger API that can be used to install breakpoints, step through and control the execution of Truffle guest language applications. The debug package is designed to be used with multiple languages and multiple threads executing at the same time.

Getting started using the debugger

First the debugger instance needs to be discovered using a Truffle guest language with Debugger.find(com.oracle.truffle.api.TruffleLanguage.Env). Next a debugger session needs to be started with Debugger.startSession(SuspendedCallback) providing a callback that will be invoked whenever the execution is suspended. The debugger client can either install a breakpoint or suspend the current or next execution. Whenever the execution is suspended and the callback is invoked the client can decide step into, step out or step over the next statements. For a usage example please refer to DebuggerSession and Breakpoint.

Enable Debugging for your Truffle guest language

The platform's core support for debugging is language-agnostic. A language implementation enables debugging by supplying extra information in every AST that configures debugger behavior for code written in that particular language.

This extra information is expressed using so called tags. Tags can be applied to AST nodes by implementing the InstrumentableNode.hasTag(Class) method. The debugger requires the guest language to implement statement and call tags from the set of standard Truffle tags. Please refer to StandardTags on how to implement them.

Since:

0.8 or older

Related Packages

Package	Description
com.oracle.truffle.api	Do you want to implement your own Truffle based language? In such case start here.

Class	Description
Breakpoint	A request that guest language program execution be suspended at specified locations on behalf of a debugging client session.
Breakpoint.Kind	Specifies a breakpoint kind.
Breakpoint.ResolveListener	This listener is called when a breakpoint is resolved at the target location.
DebugContext	Representation of a polyglot context in a guest language execution.
DebugContextsListener	Listener to be notified about changes of contexts in guest language application.
DebugException	Information about an exception thrown from a guest language.
DebugException.CatchLocation	Represents an exception catch location.
Debugger	Class that simplifies implementing a debugger on top of Truffle.
DebuggerSession	Represents a single debugging session of a Debugger.
DebuggerTags	Set of debugger-specific tags.
DebugScope	Representation of guest language scope at the current suspension point, or a top scope.
DebugStackFrame	Represents a frame in the guest language stack.
DebugStackTraceElement	Represents a trace element in the guest language stack trace.
DebugThreadsListener	Listener to be notified about changes of threads in guest language application.
DebugValue	Represents a value accessed using the debugger API.
SourceElement	Representation of a guest language source syntax element, that is used for debugging purposes.
StepConfig	Represents a debugger step configuration.
SuspendAnchor	Describes where, within a guest language source section, the suspend position is.
SuspendedCallback	Callback invoked whenever the debugger suspends for a particular session.
SuspendedEvent	Access for Debugger clients to the state of a guest language execution thread that has been suspended, for example by a Breakpoint or stepping action.
SuspensionFilter	A filter to limit the suspension locations.