Debugger (GraalVM Truffle Java API Reference)

java.lang.Object
- com.oracle.truffle.api.debug.Debugger

```
public final class Debugger
extends Object
```
Class that simplifies implementing a debugger on top of Truffle. Primarily used to implement debugging protocol support.
Access to the (singleton) instance in an engine, is available via:
To start new debugger session use Debugger.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.
Since:

0.9

See Also:

Debugger.startSession(SuspendedCallback), DebuggerSession, Breakpoint

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - startSession
```
public DebuggerSession startSession(SuspendedCallback callback)
```
    Starts a new 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.
    
    Parameters:
    
    callback - the callback to notify
    
    Since:
    
    0.17
    
    See Also:
    
    DebuggerSession, SuspendedEvent, Debugger.startSession(SuspendedCallback, SourceElement...)
  - startSession
```
public 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. 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.
    
    Parameters:
    
    callback - the callback to notify
    
    defaultSourceElements - a list of source elements, an explicit empty list disables stepping
    
    Since:
    
    0.33
    
    See Also:
    
    DebuggerSession, SuspendedEvent
  - getSessionCount
```
public int getSessionCount()
```
    Returns the number of active debugger sessions. This is useful, for instance, in deciding whether to open a new debugger session, depending on whether there is an existing one or not.
    
    Since:
    
    19.0
  - install
```
public Breakpoint install(Breakpoint breakpoint)
```
    Adds a new breakpoint to this Debugger instance and makes it available in all its sessions.
    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.
    
    Parameters:
    
    breakpoint - a new breakpoint
    
    Returns:
    
    the installed breakpoint
    
    Throws:
    
    IllegalStateException - if the session has been closed
    
    Since:
    
    0.27
  - getBreakpoints
```
public List<Breakpoint> getBreakpoints()
```
    Returns all breakpoints 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.
    
    Since:
    
    0.27
    
    See Also:
    
    DebuggerSession.getBreakpoints()
  - addBreakpointAddedListener
```
public void addBreakpointAddedListener(Consumer<Breakpoint> listener)
```
    Add a listener that is notified when a new breakpoint is added into list of breakpoints. The reported breakpoint is not modifiable.
    
    Since:
    
    19.0
  - removeBreakpointAddedListener
```
public void removeBreakpointAddedListener(Consumer<Breakpoint> listener)
```
    Remove a listener that was added by Debugger.addBreakpointAddedListener(Consumer).
    
    Since:
    
    19.0
  - addBreakpointRemovedListener
```
public void addBreakpointRemovedListener(Consumer<Breakpoint> listener)
```
    Add a listener that is notified when a breakpoint is removed from list of breakpoints. The reported breakpoint is not modifiable.
    
    Since:
    
    19.0
  - removeBreakpointRemovedListener
```
public void removeBreakpointRemovedListener(Consumer<Breakpoint> listener)
```
    Remove a listener that was added by Debugger.addBreakpointRemovedListener(Consumer).
    
    Since:
    
    19.0
  - disableStepping
```
public void disableStepping()
```
    Disable stepping on the current thread. The current thread must be in an entered context. Assure that the stepping is restored again by calling 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.
    Throws:
    
    IllegalStateException - when not in an entered context
    
    Since:
    
    22.3
    
    See Also:
    
    Debugger.restoreStepping()
  - restoreStepping
```
public void restoreStepping()
```
    Restore the stepping on the current thread. The current thread must be in an entered context and after a call to Debugger.disableStepping(). The restore decrements the disabled count by one and allows stepping when zero is reached.
    
    Throws:
    
    IllegalStateException - when not in an entered context, or when called without the preceding call to Debugger.disableStepping()
    
    Since:
    
    22.3
    
    See Also:
    
    Debugger.disableStepping()
  - find
```
public static Debugger find(TruffleInstrument.Env env)
```
    Finds the debugger associated with a given instrument environment.
    
    Parameters:
    
    env - the instrument environment to find debugger for
    
    Returns:
    
    an instance of associated debugger, never null
    
    Since:
    
    19.0
  - find
```
public static Debugger find(Engine engine)
```
    Finds the debugger associated with a given an engine.
    
    Parameters:
    
    engine - the engine to find debugger for
    
    Returns:
    
    an instance of associated debugger, never null
    
    Since:
    
    19.0
  - find
```
public static Debugger find(TruffleLanguage.Env env)
```
    Finds the debugger associated with a given language environment. There is at most one debugger associated with any 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.
    
    Parameters:
    
    env - the language environment to find debugger for
    
    Returns:
    
    an instance of associated debugger, never null
    
    Since:
    
    0.17

Class Debugger

Method Summary

Methods inherited from class java.lang.Object

Method Detail

startSession

startSession

getSessionCount

install

getBreakpoints

addBreakpointAddedListener

removeBreakpointAddedListener

addBreakpointRemovedListener

removeBreakpointRemovedListener

disableStepping

restoreStepping

find

find

find