DebuggerSession

java.lang.Object
- com.oracle.truffle.api.debug.DebuggerSession

All Implemented Interfaces:

Closeable, AutoCloseable
```
public final class DebuggerSession
extends Object
implements Closeable
```
Client access to PolyglotEngine debugging services.
Session lifetime
- A PolyglotEngine debugging client requests a new session from the engine's Debugger.
- A client uses a session to request suspension of guest language execution threads, for example by setting breakpoints or stepping.
- When a session suspends a guest language execution thread, it passes its client a new SuspendedEvent via synchronous callback on the execution thread.
- A suspended guest language execution thread resumes language execution only after the client callback returns.
- Sessions that are no longer needed should be closed; a closed session has no further affect on engine execution.
Debugging requests

Session clients can manage guest language execution in several ways:
- Install a newly created Breakpoint.
- Request suspension of the next execution on the first thread that is encountered.
- Request a stepping action (e.g. step into, step over, kill) on a suspended execution thread, to take effect after the client callback returns.
Event merging

A session may suspend a guest language execution thread in response to more than one request from its client. For example:
- A stepping action may land where a breakpoint is installed.
- Multiple installed breakpoints may apply to a particular location.
In such cases the client receives a single merged event. A call to SuspendedEvent.getBreakpoints() lists all breakpoints (possibly none) that apply to the suspended event's location.

Multiple sessions

There can be multiple sessions associated with a single engine, which are independent of one another in the following ways:

Breakpoints created by a session are not visible to clients of other sessions.
A client receives no notification when guest language execution threads are suspended by sessions other than its own.
Events are not merged across sessions. For example, when a guest language execution thread hits a location where two sessions have installed breakpoints, each session notifies its client with a new SuspendedEvent instance.

A session's client can kill an execution at just about any time.
A session's client can starve execution by not returning from the synchronous callback on the guest language execution thread.

Usage example:

PolyglotEngine engine = PolyglotEngine.newBuilder().build();

try (DebuggerSession session = Debugger.find(engine).
                startSession(new SuspendedCallback() {
    public void onSuspend(SuspendedEvent event) {
        // step into the next event
        event.prepareStepInto(1);
    }
})) {
    Source someCode = Source.newBuilder("...").
                    mimeType("...").
                    name("example").build();

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

    // should print suspended at for each debugger step.
    engine.eval(someCode);
}

Since:: 0.17

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`close()` Closes the current debugging session and disposes all installed breakpoints.
`List<Breakpoint>`	`getBreakpoints()` Returns all breakpoints in the order they were installed.
`Debugger`	`getDebugger()` Returns the `debugger` instance that this session is associated with.
`Breakpoint`	`install(Breakpoint breakpoint)` Adds a new breakpoint to this session and makes it capable of suspending execution.
`boolean`	`isBreakpointsActive()` Test whether breakpoints are active in this session.
`void`	`resumeAll()` Resumes all suspended executions that have not yet been notified.
`void`	`setBreakpointsActive(boolean active)` Set whether breakpoints are active in this session.
`void`	`setSteppingFilter(SuspensionFilter steppingFilter)` Set a stepping suspension filter.
`void`	`suspendNextExecution()` Suspends the next execution on the first thread that is encountered.
`String`	`toString()`

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

- Method Detail
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
    
    Since:
    
    0.17
  - getDebugger
```
public Debugger getDebugger()
```
    Returns the debugger instance that this session is associated with. Can be used also after the session has already been closed.
    
    Since:
    
    0.17
  - setSteppingFilter
```
public void setSteppingFilter(SuspensionFilter steppingFilter)
```
    Set a stepping suspension filter. Prepared steps skip code that match this filter.
    
    Since:
    
    0.26
  - suspendNextExecution
```
public void suspendNextExecution()
```
    Suspends the next execution on the first thread that is encountered. After the first thread was suspended no further executions are suspended unless DebuggerSession.suspendNextExecution() is called again. If multiple threads are executing at the same time then there are no guarantees on which thread is going to be suspended. Will throw an IllegalStateException if the session is already closed.
    
    Since:
    
    0.17
  - resumeAll
```
public void resumeAll()
```
    Resumes all suspended executions that have not yet been notified.
    
    Since:
    
    0.17
  - close
```
public void close()
```
    Closes the current debugging session and disposes all installed breakpoints.
    
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    Since:
    
    0.17
  - getBreakpoints
```
public List<Breakpoint> getBreakpoints()
```
    Returns all breakpoints in the order they were installed. Disposed breakpoints are automatically removed from this list.
    
    Since:
    
    0.17
  - setBreakpointsActive
```
public void setBreakpointsActive(boolean active)
```
    Set whether breakpoints are active in this session. This has no effect on breakpoints enabled/disabled state. Breakpoints need to be active to actually break the execution. The breakpoints are active by default.
    
    Parameters:
    
    active - true to make all breakpoints active, false to make all breakpoints inactive.
    
    Since:
    
    0.24
  - isBreakpointsActive
```
public boolean isBreakpointsActive()
```
    Test whether breakpoints are active in this session. Breakpoints do not break execution when not active.
    
    Since:
    
    0.24
  - install
```
public Breakpoint install(Breakpoint breakpoint)
```
    Adds a new breakpoint to this session and makes it capable of suspending execution.
    The breakpoint suspends execution by making a callback to this session, 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.17

Class DebuggerSession

Session lifetime

Debugging requests

Event merging

Multiple sessions

Method Summary

Methods inherited from class java.lang.Object

Method Detail

toString

getDebugger

setSteppingFilter

suspendNextExecution

resumeAll

close

getBreakpoints

setBreakpointsActive

isBreakpointsActive

install