Package com.oracle.truffle.api.debug

Class Debugger

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 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:

  • Method Details

    • 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 startSession(SuspendedCallback, SourceElement...) to specify a different set of source elements.
      Parameters:
      callback - the callback to notify
      Since:
      0.17
      See Also:

    • 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:

    • 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:

    • 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 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 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 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 disableStepping() increments a disabled count by one and every call to 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:

    • 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 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 disableStepping()
      Since:
      22.3
      See Also:

    • 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