DebuggerSession

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

All Implemented Interfaces:

Closeable, AutoCloseable
```
public final class DebuggerSession
extends Object
implements Closeable
```
Represents a single debugging session of a Debugger.
Session lifetime
- A debugging client requests a new session from the 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:

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

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

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 `installed` in this session, in the install order.
`Debugger`	`getDebugger()` Returns the `debugger` instance that this session is associated with.
`Map<String,? extends DebugValue>`	`getExportedSymbols()` Returns a polyglot scope - symbols explicitly exported by languages.
`DebugScope`	`getTopScope(String languageId)` Returns a language top scope.
`Breakpoint`	`install(Breakpoint breakpoint)` Adds a new breakpoint to this session and makes it capable of suspending execution.
`boolean`	`isBreakpointsActive(Breakpoint.Kind breakpointKind)` Test whether breakpoints of the given kind are active in this session.
`void`	`resumeAll()` Resumes all suspended executions that have not yet been notified.
`void`	`setBreakpointsActive(Breakpoint.Kind breakpointKind, boolean active)` Set whether breakpoints of the given kind are active in this session.
`void`	`setContextsListener(DebugContextsListener listener, boolean includeActiveContexts)` Set a `listener` to be notified about changes in contexts in guest language application.
`void`	`setSteppingFilter(SuspensionFilter steppingFilter)` Set a stepping suspension filter.
`void`	`setThreadsListener(DebugThreadsListener listener, boolean includeInitializedThreads)` Set a `listener` to be notified about changes in threads in guest language application.
`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
  - getTopScope
```
public DebugScope getTopScope(String languageId)
                       throws DebugException
```
    Returns a language top scope. The top scopes have global validity and unlike DebugStackFrame.getScope() have no relation to the suspended location.
    
    Throws:
    
    DebugException - when guest language code throws an exception
    
    Since:
    
    0.30
  - getExportedSymbols
```
public Map<String,? extends DebugValue> getExportedSymbols()
```
    Returns a polyglot scope - symbols explicitly exported by languages.
    
    Since:
    
    0.30
  - setSteppingFilter
```
public void setSteppingFilter(SuspensionFilter steppingFilter)
```
    Set a stepping suspension filter. Prepared steps skip code that does not 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 installed in this session, in the install order. The returned list contains a current snapshot of breakpoints, those that were disposed, or installed on Debugger are not included.
    
    Since:
    
    0.17
    
    See Also:
    
    Debugger.getBreakpoints()
  - setBreakpointsActive
```
public void setBreakpointsActive(Breakpoint.Kind breakpointKind,
                                 boolean active)
```
    Set whether breakpoints of the given kind 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:
    
    breakpointKind - the kind of breakpoints to activate/deactivate
    
    active - true to make breakpoints active, false to make breakpoints inactive.
    
    Since:
    
    1.0
  - isBreakpointsActive
```
public boolean isBreakpointsActive(Breakpoint.Kind breakpointKind)
```
    Test whether breakpoints of the given kind are active in this session. Breakpoints do not break execution when not active.
    
    Parameters:
    
    breakpointKind - the kind of breakpoints to test
    
    Since:
    
    1.0
  - 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
  - setContextsListener
```
public void setContextsListener(DebugContextsListener listener,
                                boolean includeActiveContexts)
```
    Set a listener to be notified about changes in contexts in guest language application. One listener can be set at a time, call with null to remove the current listener.
    
    Parameters:
    
    listener - a listener to receive the context events, or null to reset it
    
    includeActiveContexts - whether or not this listener should be notified for present active contexts
    
    Since:
    
    0.30
  - setThreadsListener
```
public void setThreadsListener(DebugThreadsListener listener,
                               boolean includeInitializedThreads)
```
    Set a listener to be notified about changes in threads in guest language application. One listener can be set at a time, call with null to remove the current listener.
    
    Parameters:
    
    listener - a listener to receive the context events
    
    includeInitializedThreads - whether or not this listener should be notified for present initialized threads
    
    Since:
    
    0.30

Class DebuggerSession

Session lifetime

Debugging requests

Event merging

Multiple sessions

Method Summary

Methods inherited from class java.lang.Object

Method Detail

toString

getDebugger

getTopScope

getExportedSymbols

setSteppingFilter

suspendNextExecution

resumeAll

close

getBreakpoints

setBreakpointsActive

isBreakpointsActive

install

setContextsListener

setThreadsListener