org.netbeans.modules.nativeimage.spi.debug

Interface NIDebuggerProvider

public interface NIDebuggerProvider

Provider of the native image debugger.

Since:

0.1

Method Summary

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

Method Detail

addLineBreakpoint

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

void removeBreakpoint(Object id)

Remove breakpoint with the given id.

Parameters:

id - the ID of the breakpoint to remove

Since:

0.1

setFrameDisplayer

void setFrameDisplayer(FrameDisplayer frameDisplayer)

Set a displayer of native frames.

Parameters:

frameDisplayer - translator of the native frame to it's displayed information

Since:

0.1

setVariablesDisplayer

void setVariablesDisplayer(VariableDisplayer variablesDisplayer)

Set a displayer of native variables.

Parameters:

variablesDisplayer - translator of native variables to displayed variables.

Since:

0.1

start

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

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

Start the actual debugging session. Called 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

Since:

0.1

start

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

Start the actual debugging session. Called 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
default CompletableFuture<Void> attach(String executablePath,
                                                   long processId,
                                                   String debugger,
                                                   java.util.function.Consumer<DebuggerEngine> startedEngine)

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

Attach to a process and create a debugging session. Called 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

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

readMemory

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

String getVersion()

Get version of the underlying native debugger.

Since:

0.1

listLocations

default List<Location> listLocations(String filePath)

Provide 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

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

Provide a list of functions in the debuggee.

Since:

0.2

listVariables

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

Provide a list of global variables in the debuggee.

Since:

0.2