Class SuspendedEvent

java.lang.Object
com.oracle.truffle.api.debug.SuspendedEvent
public final class SuspendedEvent extends Object
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.

Event lifetime

  • A DebuggerSession instruments guest language code in order to implement breakpoints, stepping actions, or other debugging actions on behalf of the session's debugger client.
  • A session may choose to suspend a guest language execution thread when it receives (synchronous) notification on the execution thread that it has reached an AST location instrumented by the session.
  • The session passes a new SuspendedEvent to the debugger client (synchronously) in a callback on the guest language execution thread.
  • Clients may access certain event state only on the execution thread where the event was created and notification received; access from other threads can throws IllegalStateException. Please see the javadoc of the individual method for details.
  • A suspended thread resumes guest language execution after the client callback returns and the thread unwinds back to instrumentation code in the AST.
  • All event methods throw IllegalStateException after the suspended thread resumes guest language execution.

Access to execution state

  • Method getStackFrames() describes the suspended thread's location in guest language code. This information becomes unusable beyond the lifetime of the event and must not be stored.
  • Method getReturnValue() describes a local result when the thread is suspended just after the code source section.

Next debugging action

Clients use the following methods to request the debugging action(s) that will take effect when the event's thread resumes guest language execution. All prepare requests accumulate until resumed.

If no debugging action is requested, the thread resumes, and any pending steps prepared by previous events remain active. An excplicit continue cancels those pending steps.

Since:
0.9

  • Method Details

    • getSession

      public DebuggerSession getSession()
      Returns the debugger session this suspended event was created for.

      This method is thread-safe.

      Since:
      0.17

    • getSourceSection

      public SourceSection getSourceSection()
      Returns the guest language source section of the AST node before/after the execution is suspended. Returns null if no source section information is available.

      This method is thread-safe.

      Since:
      0.17

    • getSuspendAnchor

      public SuspendAnchor getSuspendAnchor()
      Returns where, within the guest language source section, the suspended position is.
      Since:
      0.32

    • hasSourceElement

      public boolean hasSourceElement(SourceElement sourceElement)
      Returns true if the underlying guest language source location is denoted as the source element.
      Parameters:
      sourceElement - the source element to check, must not be null.
      Since:
      0.33

    • isLanguageContextInitialized

      public boolean isLanguageContextInitialized()
      Test if the language context of the source of the event is initialized.
      Since:
      0.26

    • getInputValues

      public DebugValue[] getInputValues()
      Returns the input values of the current source element gathered from return values of it's executed children. The input values are available only during stepping through the source elements hierarchy and only on AFTER suspend anchor. There can be null values in the returned array for children we did not intercept return values from.
      Returns:
      the array of input values, or null when no input is available.
      Since:
      0.33

    • getReturnValue

      public DebugValue getReturnValue()
      Returns the return value of the currently executed source location. Returns null if the execution is suspended before a guest language location. The returned value is null if an exception occurred during execution of the instrumented source element, the exception is provided by getException().

      This method is not thread-safe and will throw an IllegalStateException if called on another thread than it was created with.

      Since:
      0.17

    • setReturnValue

      public void setReturnValue(DebugValue newValue)
      Change the return value. When there is a return value at the current location, this method modifies the return value to a new one.
      Parameters:
      newValue - the new return value, can not be null
      Throws:
      IllegalStateException - when getReturnValue() returns null
      Since:
      19.0

    • getException

      public DebugException getException()
      Returns the debugger representation of a guest language exception that caused this suspended event (via an exception breakpoint, for instance). Returns null when no exception occurred.
      Since:
      19.0

    • isBreakpointHit

      public boolean isBreakpointHit()
      Returns true if a breakpoint hit was the reason for the suspension. A breakpoint hit can happen at the same time as a step completed and/or an unwind. Hence, a caller of this method is responsible for also taking the results of isUnwind() and isStep() into account.
      Since:
      24.1

    • isStep

      public boolean isStep()
      Returns true if a step was the reason for the suspension. A step can be either a step over, step into or a step out. A step that is completed can happen at the same time as an unwind and/or a breakpoint hit. Hence, a caller of this method is responsible for also taking the results of isUnwind() and isBreakpointHit() into account.
      Since:
      24.1

    • isUnwind

      public boolean isUnwind()
      Returns true if an unwind was the reason for the suspension. An unwind can complete at the same time as a step and/or a breakpoint hit. Hence, a caller of this method is responsible for also taking the results of isStep() and isBreakpointHit() into account.
      Since:
      24.1

    • getBreakpointConditionException

      public Throwable getBreakpointConditionException(Breakpoint breakpoint)
      Returns the cause of failure, if any, during evaluation of a breakpoint's condition.

      This method is thread-safe.

      Parameters:
      breakpoint - a breakpoint associated with this event
      Returns:
      the cause of condition failure
      Since:
      0.17

    • getBreakpoints

      public List<Breakpoint> getBreakpoints()
      Returns the breakpoints that individually would cause the "hit" where execution is suspended. If Debugger-associated breakpoint was hit, it is not possible to change the state of returned breakpoint.

      This method is thread-safe.

      Returns:
      an unmodifiable list of breakpoints
      Since:
      0.17

    • getTopStackFrame

      public DebugStackFrame getTopStackFrame()
      Returns the topmost stack frame returned by getStackFrames().

      This method is not thread-safe and will throw an IllegalStateException if called on another thread than it was created with.

      Since:
      0.17
      See Also:

    • getStackFrames

      public Iterable<DebugStackFrame> getStackFrames()
      Returns a list of guest language stack frame objects that indicate the current guest language location. There is always at least one, the topmost, stack frame available. The returned stack frames are usable only during suspend and should not be stored permanently.

      This method is not thread-safe and will throw an IllegalStateException if called on another thread than it was created with.

      Since:
      0.17

    • getAsynchronousStacks

      public List<List<DebugStackTraceElement>> getAsynchronousStacks()
      Get a list of asynchronous stack traces that led to scheduling of the current execution. Returns an empty list if no asynchronous stack is known. The first asynchronous stack is at the first index in the list. A possible next asynchronous stack (that scheduled execution of the previous one) is at the next index in the list.

      Languages might not provide asynchronous stack traces by default for performance reasons. Call DebuggerSession.setAsynchronousStackDepth(int) to request asynchronous stacks. Languages may provide asynchronous stacks if it's of no performance penalty, or if requested by other options.

      Since:
      20.1.0
      See Also:

    • prepareContinue

      public void prepareContinue()
      Prepare to execute in Continue mode when guest language program execution resumes. In this mode execution will continue until either:
      • execution arrives at a node to which an enabled breakpoint is attached, or:
      • execution completes.

      This method is thread-safe and the prepared Continue mode is appended to any other previously prepared modes. No further modes can be prepared after continue.

      Throws:
      IllegalStateException - when continue or kill is prepared already.
      Since:
      0.9

    • prepareStepInto

      public SuspendedEvent prepareStepInto(int stepCount)
      Prepare to execute in step into mode when guest language program execution resumes. See the description of prepareStepInto(StepConfig) for details, calling this is identical to prepareStepInto.(StepConfig.newBuilder().count(stepCount).build()) .
      Parameters:
      stepCount - the number of times to perform StepInto before halting
      Returns:
      this event instance for an easy concatenation of method calls
      Throws:
      IllegalArgumentException - if stepCount <= 0
      IllegalStateException - when continue or kill is prepared already.
      Since:
      0.9

    • prepareStepOut

      public SuspendedEvent prepareStepOut(int stepCount)
      Prepare to execute in step out mode when guest language program execution resumes. See the description of prepareStepOut(StepConfig) for details, calling this is identical to prepareStepOut.(StepConfig.newBuilder().count(stepCount).build()) .
      Parameters:
      stepCount - the number of times to perform StepOver before halting
      Returns:
      this event instance for an easy concatenation of method calls
      Throws:
      IllegalArgumentException - if stepCount <= 0
      IllegalStateException - when continue or kill is prepared already.
      Since:
      0.26

    • prepareStepOver

      public SuspendedEvent prepareStepOver(int stepCount)
      Prepare to execute in step over mode when guest language program execution resumes. See the description of prepareStepOver(StepConfig) for details, calling this is identical to prepareStepOver.(StepConfig.newBuilder().count(stepCount).build()) .
      Parameters:
      stepCount - the number of times to perform step over before halting
      Returns:
      this event instance for an easy concatenation of method calls
      Throws:
      IllegalArgumentException - if stepCount <= 0
      IllegalStateException - when continue or kill is prepared already.
      Since:
      0.9

    • prepareStepInto

      public SuspendedEvent prepareStepInto(StepConfig stepConfig)
      Prepare to execute in step into mode when guest language program execution resumes. In this mode, the current thread continues until it arrives to a code location with one of the enabled source elements and repeats that process step count times. See StepConfig for the details about the stepping behavior.

      This mode persists until the thread resumes and then suspends, at which time the mode reverts to Continue, or the thread dies.

      A breakpoint set at a location where execution would suspend is treated specially as a single event, to avoid multiple suspensions at a single location.

      This method is thread-safe and the prepared StepInto mode is appended to any other previously prepared modes.

      Parameters:
      stepConfig - the step configuration
      Returns:
      this event instance for an easy concatenation of method calls
      Throws:
      IllegalStateException - when continue or kill is prepared already, or when the current debugger session has no source elements enabled for stepping.
      IllegalArgumentException - when the StepConfig contains source elements not enabled for stepping in the current debugger session.
      Since:
      0.33

    • prepareStepOut

      public SuspendedEvent prepareStepOut(StepConfig stepConfig)
      Prepare to execute in step out mode when guest language program execution resumes. In this mode, the current thread continues until it arrives to an enclosing code location with one of the enabled source elements and repeats that process step count times. See StepConfig for the details about the stepping behavior.

      This mode persists until the thread resumes and then suspends, at which time the mode reverts to Continue, or the thread dies.

      A breakpoint set at a location where execution would suspend is treated specially as a single event, to avoid multiple suspensions at a single location.

      This method is thread-safe and the prepared StepInto mode is appended to any other previously prepared modes.

      Parameters:
      stepConfig - the step configuration
      Returns:
      this event instance for an easy concatenation of method calls
      Throws:
      IllegalStateException - when continue or kill is prepared already, or when the current debugger session has no source elements enabled for stepping.
      IllegalArgumentException - when the StepConfig contains source elements not enabled for stepping in the current debugger session.
      Since:
      0.33

    • prepareStepOver

      public SuspendedEvent prepareStepOver(StepConfig stepConfig)
      Prepare to execute in step over mode when guest language program execution resumes. In this mode, the current thread continues until it arrives to a code location with one of the enabled source elements, ignoring any nested ones, and repeats that process step count times. See StepConfig for the details about the stepping behavior.

      This mode persists until the thread resumes and then suspends, at which time the mode reverts to Continue, or the thread dies.

      A breakpoint set at a location where execution would suspend is treated specially as a single event, to avoid multiple suspensions at a single location.

      This method is thread-safe and the prepared StepInto mode is appended to any other previously prepared modes.

      Parameters:
      stepConfig - the step configuration
      Returns:
      this event instance for an easy concatenation of method calls
      Throws:
      IllegalStateException - when continue or kill is prepared already, or when the current debugger session has no source elements enabled for stepping.
      IllegalArgumentException - when the StepConfig contains source elements not enabled for stepping in the current debugger session.
      Since:
      0.33

    • prepareUnwindFrame

      public void prepareUnwindFrame(DebugStackFrame frame) throws IllegalArgumentException
      Prepare to unwind a frame. This frame and all frames above it are unwound off the execution stack. The frame needs to be on the execution stack of this event.
      Parameters:
      frame - the frame to unwind
      Throws:
      IllegalArgumentException - when the frame is not on the execution stack of this event
      Since:
      0.31

    • prepareUnwindFrame

      public void prepareUnwindFrame(DebugStackFrame frame, DebugValue immediateReturnValue) throws IllegalArgumentException
      Prepare to unwind a frame. This frame and all frames above it are unwound off the execution stack and the frame will return immediately with immediateReturnValue. If the return value is null, the unwound frame will instead be reentered upon thread resumption. The frame needs to be on the execution stack of this event.
      Parameters:
      frame - the frame to unwind
      immediateReturnValue - the value to return
      Throws:
      IllegalArgumentException - when the frame is not on the execution stack of this event
      Since:
      21.1.0

    • prepareKill

      public void prepareKill()
      Prepare to terminate the suspended execution represented by this event. One use-case for this method is to shield an execution of an unknown code with a timeout:

      This method is thread-safe and the prepared termination is appended to any other previously prepared modes. No further modes can be prepared after kill.

      Throws:
      IllegalStateException - when continue or kill is prepared already.
      Since:
      0.12

    • toString

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