org.netbeans.modules.nativeimage.api.debug

Class NIDebugger

java.lang.Object

org.netbeans.modules.nativeimage.api.debug.NIDebugger

public final class NIDebugger
extends Object

Representation of a native image debugger.

Since:

0.1

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	NIDebugger.Builder A builder that creates a Native Image debugger with optional displayers.

Method Summary

Modifier and Type	Method and Description
Breakpoint	addLineBreakpoint(Object id, NILineBreakpointDescriptor breakpointDescriptor) Add or change a line breakpoint into the debugger.
CompletableFuture<Void>	attach(String executablePath, long processId, String debugger, java.util.function.Consumer<DebuggerEngine> startedEngine) Deprecated. Use NIDebugger.start(StartDebugParameters, Consumer) and set StartDebugParameters.Builder.processID(Long).
NIVariable	evaluate(String expression, String resultName, NIFrame frame) A synchronous expression evaluation.
CompletableFuture<NIVariable>	evaluateAsync(String expression, String resultName, NIFrame frame) An asynchronous expression evaluation.
String	getVersion() Get version of the underlying native debugger.
Map<SourceInfo,List<Symbol>>	listFunctions(String name, boolean includeNondebug, int maxResults) Get functions of a given name.
List<Location>	listLocations(String filePath) Get a list of locations for a given file path.
Map<SourceInfo,List<Symbol>>	listVariables(String name, boolean includeNondebug, int maxResults) Get variables of a given name.
static NIDebugger.Builder	newBuilder() Creates a builder of a new debugger instance.
String	readMemory(String address, long offset, int length) Read data from memory.
void	removeBreakpoint(Object id) Remove breakpoint with the given id.
CompletableFuture<Void>	start(List<String> command, File workingDirectory, String debugger, String displayName, ExecutionDescriptor executionDescriptor, java.util.function.Consumer<DebuggerEngine> startedEngine) Deprecated. Use NIDebugger.start(org.netbeans.modules.nativeimage.api.debug.StartDebugParameters, java.util.function.Consumer)
CompletableFuture<Void>	start(StartDebugParameters debugParameters, java.util.function.Consumer<DebuggerEngine> startedEngine) Start the actual debugging session.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newBuilder

public static NIDebugger.Builder newBuilder()
                                     throws IllegalStateException

Creates a builder of a new debugger instance.

Returns:

a builder of a new debugger instance

Throws:

IllegalStateException - when the native debugger is not available (there is not an implementation of NIDebuggerServiceProvider registered in the default lookup).

Since:

0.1

addLineBreakpoint

public Breakpoint addLineBreakpoint(Object id,
                                    NILineBreakpointDescriptor breakpointDescriptor)

Add or change a line breakpoint into the debugger. A breakpoint is added when the `id` is used for the first time and modified when breakpoint with that `id` was added already.

Parameters:

id - a unique ID of the breakpoint

breakpointDescriptor - the breakpoint descriptor

Returns:

an instance of the native breakpoint

Since:

0.1

removeBreakpoint

public void removeBreakpoint(Object id)

Remove breakpoint with the given id.

Parameters:

id - the ID of the breakpoint to remove

Since:

0.1

start

@Deprecated
public CompletableFuture<Void> start(List<String> command,
                                                 File workingDirectory,
                                                 String debugger,
                                                 String displayName,
                                                 ExecutionDescriptor executionDescriptor,
                                                 java.util.function.Consumer<DebuggerEngine> startedEngine)

Deprecated. Use NIDebugger.start(org.netbeans.modules.nativeimage.api.debug.StartDebugParameters, java.util.function.Consumer)

Start the actual debugging session. Call this typically after breakpoints are added.

Parameters:

command - a command to run the native image

workingDirectory - working directory

debugger - the native debugger command

displayName - display name of the debugger task

executionDescriptor - execution descriptor that describes the runtime attributes

startedEngine - the corresponding DebuggerEngine is passed to this consumer

Returns:

future that completes on the execution finish

Since:

0.1

start

public CompletableFuture<Void> start(StartDebugParameters debugParameters,
                                     java.util.function.Consumer<DebuggerEngine> startedEngine)

Start the actual debugging session. Call this typically after breakpoints are added.

Parameters:

debugParameters - parameters to start the debugging with

startedEngine - the corresponding DebuggerEngine is passed to this consumer

Returns:

a future which is completed when the started debugger session finishes

Since:

0.5

attach

@Deprecated
public CompletableFuture<Void> attach(String executablePath,
                                                  long processId,
                                                  String debugger,
                                                  java.util.function.Consumer<DebuggerEngine> startedEngine)

Deprecated. Use NIDebugger.start(StartDebugParameters, Consumer) and set StartDebugParameters.Builder.processID(Long).

Attach to a process and create a debugging session. Call this typically after breakpoints are added.

Parameters:

executablePath - path to an executable representing the native image

processId - a process to attach to

debugger - the native debugger command

startedEngine - the corresponding DebuggerEngine is passed to this consumer

Returns:

future that completes on the execution finish

Since:

0.4

evaluateAsync

public CompletableFuture<NIVariable> evaluateAsync(String expression,
                                                   String resultName,
                                                   NIFrame frame)

An asynchronous expression evaluation.

Parameters:

expression - the expression to evaluate

resultName - preferred name of the result variable, when null the expression is used as the name

frame - the frame to evaluate at

Returns:

the completable future with the evaluation result

Since:

0.1

evaluate

public NIVariable evaluate(String expression,
                           String resultName,
                           NIFrame frame)
                    throws EvaluateException

A synchronous expression evaluation. Delegates to the asynchronous evaluation and wait for it's result.

Parameters:

expression - the expression to evaluate

resultName - preferred name of the result variable, when null the expression is used as the name

frame - the frame to evaluate at

Returns:

the evaluation result

Throws:

EvaluateException - when evaluation fails

Since:

0.1

readMemory

public String readMemory(String address,
                         long offset,
                         int length)

Read data from memory.

Parameters:

address - address where to read the data from

offset - offset relative to the address where to start reading

length - number of bytes to read

Returns:

hexadecimal representation of the memory content, or null when the read is not successful

Since:

0.1

getVersion

public String getVersion()

Get version of the underlying native debugger.

Since:

0.1

listLocations

@CheckForNull
public List<Location> listLocations(String filePath)

Get a list of locations for a given file path.

Parameters:

filePath - a file path

Returns:

list of locations, or null when there's no location information about such file.

Since:

0.2

listFunctions

@CheckForNull
public Map<SourceInfo,List<Symbol>> listFunctions(String name,
                                                                boolean includeNondebug,
                                                                int maxResults)

Get functions of a given name.

Parameters:

name - a name pattern

includeNondebug - include also symbols from the symbol table

maxResults - maximum number of results

Returns:

map of source information and their symbols, or null when there are no matching symbols.

Since:

0.2

listVariables

@CheckForNull
public Map<SourceInfo,List<Symbol>> listVariables(String name,
                                                                boolean includeNondebug,
                                                                int maxResults)

Get variables of a given name.

Parameters:

name - a name pattern

includeNondebug - include also symbols from the symbol table

maxResults - maximum number of results

Returns:

map of source information and their symbols, or null when there are no matching symbols.

Since:

0.2