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 SuspendedEvent.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 SuspendedEvent.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 then continue is assumed.
Since:

0.9

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`List<List<DebugStackTraceElement>>`	`getAsynchronousStacks()` Get a list of asynchronous stack traces that led to scheduling of the current execution.
`Throwable`	`getBreakpointConditionException(Breakpoint breakpoint)` Returns the cause of failure, if any, during evaluation of a breakpoint's condition.
`List<Breakpoint>`	`getBreakpoints()` Returns the `breakpoints` that individually would cause the "hit" where execution is suspended.
`DebugException`	`getException()` Returns the debugger representation of a guest language exception that caused this suspended event (via an exception breakpoint, for instance).
`DebugValue[]`	`getInputValues()` Returns the input values of the current source element gathered from return values of it's executed children.
`DebugValue`	`getReturnValue()` Returns the return value of the currently executed source location.
`DebuggerSession`	`getSession()` Returns the debugger session this suspended event was created for.
`SourceSection`	`getSourceSection()` Returns the guest language source section of the AST node before/after the execution is suspended.
`Iterable<DebugStackFrame>`	`getStackFrames()` Returns a list of guest language stack frame objects that indicate the current guest language location.
`SuspendAnchor`	`getSuspendAnchor()` Returns where, within the guest language `source section`, the suspended position is.
`DebugStackFrame`	`getTopStackFrame()` Returns the topmost stack frame returned by `SuspendedEvent.getStackFrames()`.
`boolean`	`hasSourceElement(SourceElement sourceElement)` Returns `true` if the underlying guest language source location is denoted as the source element.
`boolean`	`isLanguageContextInitialized()` Test if the language context of the source of the event is initialized.
`void`	`prepareContinue()` Prepare to execute in Continue mode when guest language program execution resumes.
`void`	`prepareKill()` Prepare to terminate the suspended execution represented by this event.
`SuspendedEvent`	`prepareStepInto(int stepCount)` Prepare to execute in step into mode when guest language program execution resumes.
`SuspendedEvent`	`prepareStepInto(StepConfig stepConfig)` Prepare to execute in step into mode when guest language program execution resumes.
`SuspendedEvent`	`prepareStepOut(int stepCount)` Prepare to execute in step out mode when guest language program execution resumes.
`SuspendedEvent`	`prepareStepOut(StepConfig stepConfig)` Prepare to execute in step out mode when guest language program execution resumes.
`SuspendedEvent`	`prepareStepOver(int stepCount)` Prepare to execute in step over mode when guest language program execution resumes.
`SuspendedEvent`	`prepareStepOver(StepConfig stepConfig)` Prepare to execute in step over mode when guest language program execution resumes.
`void`	`prepareUnwindFrame(DebugStackFrame frame)` Prepare to unwind a frame.
`void`	`prepareUnwindFrame(DebugStackFrame frame, DebugValue immediateReturnValue)` Prepare to unwind a frame.
`void`	`setReturnValue(DebugValue newValue)` Change the return value.
`String`	`toString()`

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

- Method Detail
  - 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 SuspendedEvent.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 SuspendedEvent.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
  - 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 SuspendedEvent.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:
    
    SuspendedEvent.getStackFrames()
  - 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:
    
    DebuggerSession.setAsynchronousStackDepth(int)
  - 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 SuspendedEvent.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 SuspendedEvent.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 SuspendedEvent.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

Class SuspendedEvent

Event lifetime

Access to execution state

Next debugging action

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getSession

getSourceSection

getSuspendAnchor

hasSourceElement

isLanguageContextInitialized

getInputValues

getReturnValue

setReturnValue

getException

getBreakpointConditionException

getBreakpoints

getTopStackFrame

getStackFrames

getAsynchronousStacks

prepareContinue

prepareStepInto

prepareStepOut

prepareStepOver

prepareStepInto

prepareStepOut

prepareStepOver

prepareUnwindFrame

prepareUnwindFrame

prepareKill

toString