Package com.oracle.truffle.api.debug

Class Breakpoint

java.lang.Object
com.oracle.truffle.api.debug.Breakpoint
public class Breakpoint extends Object
A request that guest language program execution be suspended at specified locations on behalf of a debugging client session.

Breakpoint lifetime

  • A client of a DebuggerSession uses a Breakpoint.Builder to create a new breakpoint, choosing among multiple ways to specify the intended location. Examples include a specified source, a specified URI, line ranges, or an exact SourceSection.
  • A new breakpoint cannot affect execution until after it has been installed by a session, which may be done only once.
  • A breakpoint that is both installed and enabled (true by default) will suspend any guest language execution thread that arrives at a matching AST location. The breakpoint (synchronously) calls back to the responsible session on the execution thread.
  • A breakpoint may be enabled or disabled any number of times.
  • A breakpoint that is no longer needed may be disposed. A disposed breakpoint:
    • is disabled
    • is not installed in any session
    • can have no effect on program execution, and
    • must not be used again.
  • A session being closed disposes all installed breakpoints.

Example usage: 

try (DebuggerSession session = Debugger.find(instrumentEnvironment).
                startSession(suspendedCallback)) {

    // install breakpoint in someCode at line 3.
    session.install(Breakpoint.newBuilder(someCode).
                    lineIs(3).build());

    // install breakpoint for a URI at line 3
    session.install(Breakpoint.newBuilder(someCode.getURI()).
                    lineIs(3).build());

}
Since:
0.9

  • Method Details

    • getKind

      public Breakpoint.Kind getKind()
      Returns the kind of this breakpoint.
      Since:
      19.0

    • isDisposed

      public boolean isDisposed()
      Returns:
      whether this breakpoint is permanently unable to affect execution
      Since:
      0.17
      See Also:

    • isEnabled

      public boolean isEnabled()
      Returns:
      whether this breakpoint is currently allowed to suspend execution (true by default)
      Since:
      0.9
      See Also:

    • setEnabled

      public void setEnabled(boolean enabled)
      Controls whether this breakpoint is currently allowed to suspend execution (true by default). This can be changed arbitrarily until breakpoint is disposed.

      When not modifiable, IllegalStateException is thrown.

      Parameters:
      enabled - whether this breakpoint should be allowed to suspend execution
      Since:
      0.9

    • isResolved

      public boolean isResolved()
      Returns:
      whether at least one source has been loaded that contains a match for this breakpoint's location.
      Since:
      0.17

    • setCondition

      public void setCondition(String expression)
      Assigns to this breakpoint a boolean expression whose evaluation will determine whether the breakpoint suspends execution (i.e. "hits"), null to remove any condition and always suspend.

      Breakpoints are by default unconditional.

      Evaluation: expressions are parsed and evaluated in the lexical context of the breakpoint's location. A conditional breakpoint that applies to multiple code locations will be parsed and evaluated separately for each location.

      Evaluation failure: when evaluation of a condition fails for any reason, including the return of a non-boolean value:

      • execution suspends, as if evaluation had returned true, and
      • a message is logged that can be retrieved while execution is suspended.
      When not modifiable, IllegalStateException is thrown.
      Parameters:
      expression - if non-null, a boolean expression, expressed in the guest language of the breakpoint's location.
      Since:
      0.9
      See Also:

    • getCondition

      public String getCondition()
      Returns the expression used to create the current breakpoint condition, null if no condition set.
      Since:
      0.20

    • dispose

      public void dispose()
      Permanently prevents this breakpoint from affecting execution. When not modifiable, IllegalStateException is thrown.
      Since:
      0.9

    • isOneShot

      public boolean isOneShot()
      Returns:
      whether this breakpoint disables itself after suspending execution, i.e. on first hit
      Since:
      0.9

    • getIgnoreCount

      public int getIgnoreCount()
      Returns:
      the number of times breakpoint will be executed but not hit (i.e. suspend execution).
      Since:
      0.9
      See Also:

    • setIgnoreCount

      public void setIgnoreCount(int ignoreCount)
      Changes the number of times the breakpoint must be executed before it hits (i.e. suspends execution).

      When a breakpoint condition evaluates to false:

      • execution is not suspended
      • it does not count as a hit
      • the remaining ignoreCount does not change.
      When not modifiable, IllegalStateException is thrown.
      Parameters:
      ignoreCount - number of breakpoint activations to ignore before it hits
      Since:
      0.9

    • getHitCount

      public int getHitCount()
      Returns:
      the number of times this breakpoint has suspended execution
      Since:
      0.9

    • getLocationDescription

      public String getLocationDescription()
      Returns:
      a description of this breakpoint's specified location
      Since:
      0.9

    • getSuspendAnchor

      public SuspendAnchor getSuspendAnchor()
      Returns the suspended position within the guest language source location.
      Since:
      0.32

    • isModifiable

      public boolean isModifiable()
      Test whether this breakpoint can be modified. When false, methods that change breakpoint state throw IllegalStateException.

      Unmodifiable breakpoints are created from installed breakpoints as read-only copies to be available to clients other than the one who installed the original breakpoint. Debugger.getBreakpoints() returns unmodifiable breakpoints, for instance.

      Returns:
      whether this breakpoint can be modified.
      Since:
      0.27

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Since:
      0.9

    • newBuilder

      public static Breakpoint.Builder newBuilder(URI sourceUri)
      Creates a new breakpoint builder based on a URI location.
      Parameters:
      sourceUri - a URI to specify breakpoint location
      Since:
      0.17

    • newBuilder

      public static Breakpoint.Builder newBuilder(Source source)
      Creates a new breakpoint builder based on a Source.
      Parameters:
      source - a Source to specify breakpoint location
      Since:
      0.17

    • newBuilder

      public static Breakpoint.Builder newBuilder(SourceSection sourceSection)
      Creates a new breakpoint builder based on the textual region of a guest language source element.
      Parameters:
      sourceSection - a specification for guest language source element
      Since:
      0.17

    • newExceptionBuilder

      public static Breakpoint.ExceptionBuilder newExceptionBuilder(boolean caught, boolean uncaught)
      Creates a new exception breakpoint builder. The exception breakpoint can be set to intercept caught or uncaught exceptions, or both. At least one argument needs to be true. The builder creates breakpoint of EXCEPTION kind.
      Parameters:
      caught - true to intercept exceptions that are caught by guest language code.
      uncaught - true to intercept exceptions that are not caught by guest language code.
      Since:
      19.0