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.
`DebugValue`	`createPrimitiveValue(Object primitiveValue, LanguageInfo language)` Creates a `DebugValue` object that wraps a primitive value.
`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.
`Source`	`resolveSource(Source source)` Resolve the source with respect to the actual `source path`.
`void`	`resume(Thread t)` Resumes the execution on a given thread if it has not been suspended yet.
`void`	`resumeAll()` Resumes all suspended executions that have not yet been notified.
`void`	`setAsynchronousStackDepth(int depth)` Request for languages to provide stack frames of scheduled asynchronous execution.
`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`	`setShowHostStackFrames(boolean showHostStackFrames)` Set to provide host information in stack traces.
`void`	`setSourcePath(Iterable<URI> uris)` Set a list of source path roots that are used to resolve relative `source URIs`.
`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`	`suspend(Thread t)` Suspends the current or the next execution of a given thread.
`void`	`suspendAll()` Suspends the current or the next execution on all threads.
`boolean`	`suspendHere(Node node)` Suspend immediately at the current location of the current execution thread.
`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
  - setShowHostStackFrames
```
public void setShowHostStackFrames(boolean showHostStackFrames)
```
    Set to provide host information in stack traces. When true, host frames and host trace elements are provided, when available.
    
    Since:
    
    20.3
    
    See Also:
    
    DebugStackFrame.isHost(), DebugStackTraceElement.isHost()
  - 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
  - suspendHere
```
public boolean suspendHere(Node node)
```
    Suspend immediately at the current location of the current execution thread. A Node argument can be provided as an exact current location, if known. This method can be called on the guest execution thread only.
    This method calls SuspendedCallback.onSuspend(SuspendedEvent) synchronously, with SuspendedEvent created at the actual location of the current thread. This method can not be called from an existing callback.
    
    Parameters:
    
    node - the top Node of the execution, or null
    
    Returns:
    
    true when there is a guest code execution on the current thread and SuspendedCallback was called, false otherwise.
    
    Throws:
    
    IllegalStateException - when the current thread is suspended already
    
    IllegalArgumentException - when a node with no RootNode is provided, or it's root node does not match the current execution root, or the node does not match the current call node, if known.
    
    Since:
    
    20.3
  - suspend
```
public void suspend(Thread t)
```
    Suspends the current or the next execution of a given thread. Will throw an IllegalStateException if the session is already closed.
    
    Since:
    
    20.0
  - suspendAll
```
public void suspendAll()
```
    Suspends the current or the next execution on all threads. All new executing threads will start suspended until DebuggerSession.resumeAll() is called or the session is closed. Will throw an IllegalStateException if the session is already closed.
    
    Since:
    
    20.0
  - resumeAll
```
public void resumeAll()
```
    Resumes all suspended executions that have not yet been notified.
    
    Since:
    
    0.17
  - resume
```
public void resume(Thread t)
```
    Resumes the execution on a given thread if it has not been suspended yet.
    
    Parameters:
    
    t - the thread to resume
    
    Since:
    
    20.0
  - createPrimitiveValue
```
public DebugValue createPrimitiveValue(Object primitiveValue,
                                       LanguageInfo language)
                                throws IllegalArgumentException
```
    Creates a DebugValue object that wraps a primitive value. Strings and boxed Java primitive types are considered primitive. Throws IllegalArgumentException if the value is not primitive.
    
    Parameters:
    
    primitiveValue - a primitive value
    
    language - guest language this value is value is associated with. Some value attributes depend on the language, like DebugValue.getMetaObject(). Can be null.
    
    Returns:
    
    a DebugValue that wraps the primitive value.
    
    Throws:
    
    IllegalArgumentException - if the value is not a boxed Java primitive or a String.
    
    Since:
    
    21.2
  - 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:
    
    19.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:
    
    19.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
  - setAsynchronousStackDepth
```
public void setAsynchronousStackDepth(int depth)
```
    Request for languages to provide stack frames of scheduled asynchronous execution. Languages might not provide asynchronous stack frames by default for performance reasons. At most depth asynchronous stack frames are asked for. When multiple debugger sessions or other instruments call this method, the languages get a maximum depth of these calls and may therefore provide longer asynchronous stacks than requested. Also, languages may provide asynchronous stacks if it's of no performance penalty, or if requested by other options.
    Asynchronous stacks can then be accessed via SuspendedEvent.getAsynchronousStacks(), or DebugException.getDebugAsynchronousStacks().
    
    Parameters:
    
    depth - the requested stack depth, 0 means no asynchronous stack frames are required.
    
    Since:
    
    20.1.0
    
    See Also:
    
    SuspendedEvent.getAsynchronousStacks(), DebugException.getDebugAsynchronousStacks()
  - 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
  - setSourcePath
```
public void setSourcePath(Iterable<URI> uris)
```
    Set a list of source path roots that are used to resolve relative source URIs. All debugger methods that provide Source object, resolve relative sources with respect to this source-path. When the resolution does not succeed (the relative path does not exist under any of the supplied source-path elements), the original relative Source is provided.
    
    Parameters:
    
    uris - a list of absolute URIs
    
    Throws:
    
    IllegalArgumentException - when an URI is not absolute
    
    Since:
    
    19.0
    
    See Also:
    
    DebuggerSession.resolveSource(Source)
  - resolveSource
```
public Source resolveSource(Source source)
```
    Resolve the source with respect to the actual source path. Sources with relative URI are subject to resolution to an existing absolute location. The first source-path URI that resolves to an existing location is used.
    
    Parameters:
    
    source - the source to resolve
    
    Returns:
    
    the provided source if no resolution is necessary, or the resolved source, or null when it's not possible to resolve the provided source
    
    Since:
    
    19.0

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

setShowHostStackFrames

setSteppingFilter

suspendNextExecution

suspendHere

suspend

suspendAll

resumeAll

resume

createPrimitiveValue

close

getBreakpoints

setBreakpointsActive

isBreakpointsActive

install

setAsynchronousStackDepth

setContextsListener

setThreadsListener

setSourcePath

resolveSource