public final class Debugger extends Object
Access to the (singleton) instance in an engine, is available via:
To start new debugger session useDebugger.startSession(SuspendedCallback)
. Please see
DebuggerSession
for a usage example.
The debugger supports diagnostic tracing that can be enabled using the
-Dtruffle.debug.trace=true
Java property. The output of this tracing is not
guaranteed and will change without notice.
Debugger.startSession(SuspendedCallback)
,
DebuggerSession
,
Breakpoint
Modifier and Type | Method and Description |
---|---|
void |
addBreakpointAddedListener(Consumer<Breakpoint> listener)
Add a listener that is notified when a new breakpoint is added into
list of breakpoints . |
void |
addBreakpointRemovedListener(Consumer<Breakpoint> listener)
Add a listener that is notified when a breakpoint is removed from
list of breakpoints . |
void |
disableStepping()
Disable stepping on the current thread.
|
static Debugger |
find(Engine engine)
Finds the debugger associated with a given an engine.
|
static Debugger |
find(TruffleInstrument.Env env)
Finds the debugger associated with a given instrument environment.
|
static Debugger |
find(TruffleLanguage.Env env)
Finds the debugger associated with a given language environment.
|
List<Breakpoint> |
getBreakpoints()
Returns all breakpoints
installed
in this debugger instance, in the install order. |
int |
getSessionCount()
Returns the number of active debugger sessions.
|
Breakpoint |
install(Breakpoint breakpoint)
Adds a new breakpoint to this Debugger instance and makes it available in all its sessions.
|
void |
removeBreakpointAddedListener(Consumer<Breakpoint> listener)
Remove a listener that was added by
Debugger.addBreakpointAddedListener(Consumer) . |
void |
removeBreakpointRemovedListener(Consumer<Breakpoint> listener)
Remove a listener that was added by
Debugger.addBreakpointRemovedListener(Consumer) . |
void |
restoreStepping()
Restore the stepping on the current thread.
|
DebuggerSession |
startSession(SuspendedCallback callback)
Starts a new
session provided with a callback that gets notified
whenever the execution is suspended. |
DebuggerSession |
startSession(SuspendedCallback callback,
SourceElement... defaultSourceElements)
Starts a new
session provided with a callback that gets notified
whenever the execution is suspended and with a list of source syntax elements on which it is
possible to step. |
public DebuggerSession startSession(SuspendedCallback callback)
session
provided with a callback that gets notified
whenever the execution is suspended. Uses SourceElement.STATEMENT
as the source
element available for stepping. Use
Debugger.startSession(SuspendedCallback, SourceElement...)
to specify a different set of
source elements.callback
- the callback to notifyDebuggerSession
,
SuspendedEvent
,
Debugger.startSession(SuspendedCallback, SourceElement...)
public DebuggerSession startSession(SuspendedCallback callback, SourceElement... defaultSourceElements)
session
provided with a callback that gets notified
whenever the execution is suspended and with a list of source syntax elements on which it is
possible to step. Only steps created with one of these element kinds are accepted in this
session. All specified elements are used by steps by default, if not specified otherwise by
StepConfig.Builder.sourceElements(SourceElement...)
. When no elements are provided,
stepping is not possible and the session itself has no instrumentation overhead.callback
- the callback to notifydefaultSourceElements
- a list of source elements, an explicit empty list disables
steppingDebuggerSession
,
SuspendedEvent
public int getSessionCount()
public Breakpoint install(Breakpoint breakpoint)
The breakpoint suspends execution in all active sessions
by making a
callback to the appropriate session callback handler
, together with
an event description that includes which
breakpoint(s) were hit.
breakpoint
- a new breakpointIllegalStateException
- if the session has been closedpublic List<Breakpoint> getBreakpoints()
installed
in this debugger instance, in the install order. The returned list contains a current
snapshot of breakpoints, those that were disposed
are not
included.
It's not possible to modify state of breakpoints returned from this list, or from methods on
listeners, they are not modifiable
. An attempt to modify
breakpoints state using any of their set method, or an attempt to dispose such breakpoints,
fails with an IllegalStateException
. Use the original installed breakpoint instance
to change breakpoint state or dispose the breakpoint.
DebuggerSession.getBreakpoints()
public void addBreakpointAddedListener(Consumer<Breakpoint> listener)
list of breakpoints
. The reported breakpoint is not modifiable
.public void removeBreakpointAddedListener(Consumer<Breakpoint> listener)
Debugger.addBreakpointAddedListener(Consumer)
.public void addBreakpointRemovedListener(Consumer<Breakpoint> listener)
list of breakpoints
. The reported breakpoint is not modifiable
.public void removeBreakpointRemovedListener(Consumer<Breakpoint> listener)
Debugger.addBreakpointRemovedListener(Consumer)
.public void disableStepping()
Debugger.restoreStepping()
like:
Debugger
debugger =Debugger
.find(engine); debugger.disableStepping(); try { // run code which debugger should not step into } finally { debugger.restoreStepping(); }
The typical usage is to disable stepping on a specific code path. E.g. when a guest code is
executed as a safepoint action, which executes out of an apparent code flow. The calls to
disable/restoreStepping can be nested. Every call to Debugger.disableStepping()
increments a
disabled count by one and every call to Debugger.restoreStepping()
decrements the disabled
count by one.
Disabling of stepping does not prevent breakpoints from being hit. After a breakpoint is hit, stepping is allowed automatically for the breakpoint's session, so that the user can continue stepping from the breakpoint location. The stepping is allowed only on the level of the disabled count where the breakpoint is hit. The stepping is still disabled on other disabled count levels.
IllegalStateException
- when not in an entered contextDebugger.restoreStepping()
public void restoreStepping()
Debugger.disableStepping()
. The restore decrements the disabled count by
one and allows stepping when zero is reached.IllegalStateException
- when not in an entered context, or when called without the
preceding call to Debugger.disableStepping()
Debugger.disableStepping()
public static Debugger find(TruffleInstrument.Env env)
env
- the instrument environment to find debugger fornull
public static Debugger find(Engine engine)
engine
- the engine to find debugger fornull
public static Debugger find(TruffleLanguage.Env env)
Engine
. Please note that a debugger
instance looked up with a language also has access to all other languages and sources that
were loaded by them.env
- the language environment to find debugger fornull