Class NearestSectionFilter

java.lang.Object

com.oracle.truffle.api.instrumentation.NearestSectionFilter

public final class NearestSectionFilter
extends Object

Add a filter for source sections that are nearest to the given source position, according to the guest language control flow.

The selection of the nearest source location happens based on the provided SourceSectionFilter and this nearest section filter to the Instrumenter create/attach methods. First location candidates are selected according to the SourceSectionFilter. Based on this selection a nearest location is found using this NearestSectionFilter. If new nearer locations are loaded then the listener/factory will be notified again. There is at most one nearest SourceSection at a time, therefore it is possible to detect updates by remembering and comparing the source section in the listener/factory.

Start building the nearest filter by calling newBuilder(int, int) and complete it by calling NearestSectionFilter.Builder.build().

A use-case is a debugger breakpoint, for instance, where the exact line or column is not always precise and the location needs to be updated when new code is loaded.

Since:

23.0

See Also:

• newBuilder(int, int)
• Instrumenter.createLoadSourceSectionBinding(NearestSectionFilter, SourceSectionFilter, LoadSourceSectionListener, boolean)
• Instrumenter.attachLoadSourceSectionListener(NearestSectionFilter, SourceSectionFilter, LoadSourceSectionListener, boolean)
• Instrumenter.attachExecutionEventFactory(NearestSectionFilter, SourceSectionFilter, ExecutionEventNodeFactory)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	NearestSectionFilter.Builder	Builder to configure NearestSectionFilter before creating its instance.

Method Summary

Modifier and Type	Method	Description
static NearestSectionFilter.Builder	newBuilder(int line, int column)	Creates a new NearestSectionFilter using a builder pattern.
String	toString()

Methods inherited from class java.lang.Object

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

Method Details

newBuilder

public static NearestSectionFilter.Builder newBuilder(int line,
 int column)

Creates a new NearestSectionFilter using a builder pattern. The filter will find source sections that are nearest to the given source line and column. To create the final filter finalize it using NearestSectionFilter.Builder.build().

Parameters:

line - the line, greater than or equal to 1

column - the column, or < 1 when column is unknown

Returns:

a new builder to create new NearestSectionFilter instances

Since:

23.0

toString

public String toString()

Overrides:

toString in class Object

Returns:

the filter attributes in a human readable form for debugging.

Since:

23.0