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.

See: Description

Interface Summary

Interface	Description
SuspendedCallback	Callback invoked whenever the debugger suspends for a particular session.

Class Summary

Class	Description
Breakpoint	A request that guest language program execution be suspended at specified locations on behalf of a debugging client session.
Debugger	Represents debugging related state of a PolyglotEngine.
DebuggerSession	Client access to PolyglotEngine debugging services.
DebuggerTags	Set of debugger-specific tags.
DebugScope	Representation of guest language scope at the current suspension point.
DebugStackFrame	Represents a frame in the guest language stack.
DebugValue	Represents a value accessed using the debugger API.
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 skip certain suspension locations.

Package com.oracle.truffle.api.debug Description

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 Debugger.find(com.oracle.truffle.api.vm.PolyglotEngine) instance or from 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.

There is also a list of FAQs that may provide useful hints when writing your own Truffle debugger frontend.

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 Node.isTaggedWith(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