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 a frame.
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
`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.
`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.
`DebugStackFrame`	`getTopStackFrame()` Returns the topmost stack frame returned by `SuspendedEvent.getStackFrames()`.
`boolean`	`isHaltedBefore()` Returns `true` if the execution is suspended before executing a guest language source location.
`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 StepInto mode when guest language program execution resumes.
`SuspendedEvent`	`prepareStepOut(int stepCount)` Prepare to execute in StepOut mode when guest language program execution resumes.
`SuspendedEvent`	`prepareStepOver(int stepCount)` Prepare to execute in StepOver mode when guest language program execution resumes.
`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
  - isHaltedBefore
```
public boolean isHaltedBefore()
```
    Returns true if the execution is suspended before executing a guest language source location. Returns false if it was suspended after.
    This method is thread-safe..
    
    Since:
    
    0.14
  - isLanguageContextInitialized
```
public boolean isLanguageContextInitialized()
```
    Test if the language context of the source of the event is initialized.
    
    Since:
    
    0.26
  - 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 statement. The debug value remains valid event if the current execution was suspend.
    This method is not thread-safe and will throw an IllegalStateException if called on another thread than it was created with.
    
    Since:
    
    0.17
  - 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.
    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
  - 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 StepInto mode when guest language program execution resumes. In this mode:
    - Execution, when resumed, continues until either:
      
      execution arrives at at the nth node (specified by stepCount) with the tag StandardTags.StatementTag, or
      
      execution arrives at a Breakpoint, or
      
      execution completes.
    - The mode persists only until either:
      
      program execution resumes and then halts, at which time the mode reverts to Continue, or
      
      execution completes, at which time the mode reverts to Continue.
    - A breakpoint set at a location where execution would halt is treated specially to avoid a "double halt" during stepping:
      
      execution halts only once at the location;
      
      the halt counts as a breakpoint hit;
      
      the mode reverts to Continue, as if there were no breakpoint; and
      
      this special treatment applies only for breakpoints created before the mode is set.
    This method is thread-safe and the prepared StepInto mode is appended to any other previously prepared modes.
    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 StepOut mode when guest language program execution resumes. In this mode:
    - Execution, when resumed, continues until either:
      
      execution arrives at the nth enclosing call site on the stack (specified by stepCount), or
      
      execution arrives at a Breakpoint, or
      
      execution completes.
    - The mode persists only until either:
      
      program execution resumes and then halts, at which time the mode reverts to Continue, or
      
      execution completes, at which time the mode reverts to Continue.
    This method is thread-safe and the prepared StepOut mode is appended to any other previously prepared modes.
    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 StepOver mode when guest language program execution resumes. In this mode:
    - Execution, when resumed, continues until either:
      
      execution arrives at at the nth node (specified by stepCount) with the tag StandardTags.StatementTag, ignoring nodes nested in function/method calls, or
      
      execution arrives at a Breakpoint, or
      
      execution completes.
    - The mode persists only until either:
      
      program execution resumes and then halts, at which time the mode reverts to Continue, or
      
      execution completes, at which time the mode reverts to Continue.
    - A breakpoint set at a location where execution would halt is treated specially to avoid a "double halt" during stepping:
      
      execution halts only once at the location;
      
      the halt counts as a breakpoint hit;
      
      the mode reverts to Continue, as if there were no breakpoint; and
      
      this special treatment applies only for breakpoints created before the mode is set.
      
      This method is thread-safe and the prepared StepOver mode is appended to any other previously prepared modes.
    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.9
  - 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:
```
class ExecWithTimeOut {

    boolean pauseRequested;

    void executeWithTimeOut(
                    ScheduledExecutorService executor, // run us later
                    PolyglotEngine.Value function, // unknown function
                    Object parameter // parameter of the function
    ) {
        executor.schedule(new Runnable() {
            public void run() {
                Debugger.find(engine).startSession(new SuspendedCallback() {
                    public void onSuspend(SuspendedEvent event) {
                        pauseRequested = true;
                        event.prepareKill();
                    }
                });
            }
        }, 10, TimeUnit.SECONDS);

        Throwable caught = null;
        try {
            // execute with timer on
            function.execute(parameter);
        } catch (ThreadDeath t) {
            caught = t;
        }
        if (pauseRequested) {
            assertTrue("Pause requested", pauseRequested);
            assertNotNull("Execution ended with throwable", caught);
            assertEquals("Our Exception", // prepareKill produces
                            "com.oracle.truffle.api.debug.KillException", //
                            caught.getClass().getName());
        }
    }
}
```
    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

isHaltedBefore

isLanguageContextInitialized

getReturnValue

getBreakpointConditionException

getBreakpoints

getTopStackFrame

getStackFrames

prepareContinue

prepareStepInto

prepareStepOut

prepareStepOver

prepareKill

toString