public final class Insight extends Object
Insight.ID
:
finaland thenEngine
engine = context.getEngine();Instrument
instrument = engine.getInstruments().get("insight");Function
<Source
,AutoCloseable
> access = instrument.lookup(Function
.class);AutoCloseable
handle = access.apply(agentSrc);
evaluate
Source
scripts written in any language accessing the agent
variable exposed to them. Use
following API
when dealing with the insight
variable:
/** Instance of this class is accessible via {@code insight} variable * in theInsight
scripts registered to the instrument. */ public interface InsightAPI { /** ID of the instrument. Version {@code 1.1} has been released as * part of GraalVM 21.1.0 release. * * @return same value of {@linkInsight
#ID} - e.g. {@code "insight"} * @since 0.3 */String
id(); /** Version of the API. Version {@code 1.1} has been released as * part of GraalVM 21.1.0 release. * * @return same value of {@linkInsight
#VERSION} * @since 0.1 */String
version(); /** Marker interface for any handler. * @since 0.1 */ interface Handler { } interface SourceInfo { /** Name of the {@link OnSourceLoadedHandler#sourceLoaded}. * @return name of the loaded source * @since 0.1 */String
name(); /**Character
content of the {@link OnSourceLoadedHandler#sourceLoaded}. * @return content of the loaded source * @since 0.1 */String
characters(); /** Identification of this source's language. * @returnString
representing the language ID * @since 0.1 */String
language(); /** Mime type of this source. * @return given mime type or {@code null} * @since 0.1 */String
mimeType(); /** URI uniquely identifying the source. * @return the URI * @since 0.1 */String
uri(); } interface SourceSectionInfo { /** * Name of the enclosing function. * * @return the name of the enclosing function * @since 0.1 */String
name(); /** * Information about surrounding source. * * @return information about the surrounding source * @since 0.4 */ SourceInfo source(); /** * Characters of the location. * * @return the characters of this {@link OnEventHandler.Context} * @since 0.4 */String
characters(); /** * Line of this location. The same as {@link #startLine()}. * * @return line number counting from one * @since 0.4 */ int line(); /** * Staring line of this location. * * @return line number counting from one * @since 0.4 */ int startLine(); /** * Final line of this location. * * @return line number counting from one * @since 0.4 */ int endLine(); /** * Column of this location. The same as {@link #startColumn()}. * * @return column number counting from one * @since 0.4 */ int column(); /** * Starting column of this location. * * @return column number counting from one * @since 0.4 */ int startColumn(); /** * Final column of this location. * * @return column number counting from one * @since 0.4 */ int endColumn(); /** * Returns the 0-based index of the first character in this section. * Returns <code>0</code> for unavailable source * sections. * * @return the starting character index * @since 1.1 */ int charIndex(); /** * Returns the length of this section in characters. Returns * <code>0</code> for unavailable source * sections. * * @return the number of characters in the section * @since 1.1 */ int charEndIndex(); /** * Returns the index of the text position immediately following the last * character in the section. * Returns <code>0</code> for unavailable source sections. * * @return the end position of the section * @since 1.1 */ int charLength(); } @FunctionalInterface
interface OnSourceLoadedHandler extends Handler { /** Called when a new source is loaded into the system. * @param info information about the loaded source * @since 0.1 */ void sourceLoaded(SourceInfo info); } /** Register a handler to be notified when a source is loaded. * * @param event has to be {@code "source"} string * @param handler a callback that takes * {@link SourceInfo one argument} */ void on(String
event, OnSourceLoadedHandler handler); @FunctionalInterface
interface OnEventHandler extends Handler { interface Context extends SourceSectionInfo { /** The current return value to be returned unless * {@link #returnNow} is called. The only meaningful * values can be expected inside of {@link #on on("return", ...)} * handlers. * * @param frame object with variables provided * as a second parameter to {@link OnEventHandler#event event} * method * @return the current return value or {@code null}, * if not applicable * @since 0.7 */Object
returnValue(Map
<String
,Object
> frame); /** Immediatelly exits the current handler and returns to the * caller. Calling this method aborts execution of the current * handler. It bypasses language sematics and immediatelly * returns the provided value to the caller. If there are multiple * calls to {@code returnNow} (from different handlers) the * first call defines the return value. * * @param value the value to return to the caller * @since 0.7 * @see #returnValue(java.util.Map
) */ void returnNow(Object
value); /** Walks the stack at current execution point and iterates through * invocation frames and their local values. * * @param <T> type to return from the iterator * @param it iterator to call for each frame * (that is not {@linkSource
#isInternal() internal}) * @return first non-{@code null} value returned * from the {@code it} iterator or {@code null} * @since 1.0 */ <T> T iterateFrames(FramesIterator<T> it); } void event(Context ctx,Map
<String
,Object
> frame); } /** Iterator for the {@link OnEventHandler.Context#iterateFrames}. * @since 1.0 */ @FunctionalInterface
interface FramesIterator<T> { /** Called for each frame found on the stack. * * @param at location in the source code * @param frame access to local variables * @return {@code null} to continue iteration, non-{@code null} to * return immediatelly from the * {@link OnEventHandler.Context#iterateFrames} method. */ T onFrame(SourceSectionInfo at,Map
<String
,Object
> frame); } class OnConfig { public boolean expressions; public boolean statements; public boolean roots; /**String
with a regular expression to match name of functions. * Prior to version 0.6 this had to be a * {@code Function<String
,Boolean
>}. */ publicString
rootNameFilter; /* @since 0.4 */ publicPredicate
<SourceInfo> sourceFilter; /** *org.graalvm.tools.lsp.server.types.Location
in the source file. * @since 1.2 */ public OnConfigAt at; } class OnConfigAt { /** *String
with a regular expression to match source path. * Exactly one of this or {@link #sourceURI} is a mandatory property of * the `at` object. * @since 1.2 */ publicString
sourcePath; /** *String
representation of a source URI. * Exactly one of this or {@link #sourcePath} is a mandatory property of * the `at` object. * @since 1.2 */ publicString
sourceURI; /** * The line to match. * @since 1.2 */ publicObject
line; /** * The column to match. * @since 1.2 */ publicObject
column; } /** Register a handler on a particular elements in the source code. * * @param event one of {@code "enter"}, {@code "return"} strings * @param handler callback * {@link OnEventHandler#event function with two arguments} * @param config config object to identify locations to listen to */ void on(String
event, OnEventHandler handler, OnConfig config); @FunctionalInterface
interface OnCloseHandler extends Handler { void closed(); } /** Register on close handler. * * @param event must be {@code "close"} string * @param handler no args function to be notified when execution ends */ void on(String
event, OnCloseHandler handler); /** Unregisters a handler. * * @param event the event type to unregister from * @param handler the instance of handler registered * by one of the {@code on} methods * @since 0.2 */ void off(String
event, Handler handler); }
Modifier and Type | Class and Description |
---|---|
static interface |
Insight.SymbolProvider
Additional provider of symbols for
Insight scripts . |
public static final String ID
"insight"
. Use it to obtain access to an
Insight
instruments inside of your Engine
:
finalEngine
engine = context.getEngine();Instrument
instrument = engine.getInstruments().get("insight");Function
<Source
,AutoCloseable
> access = instrument.lookup(Function
.class);AutoCloseable
handle = access.apply(agentSrc);
public static final String VERSION
insight
reference:
/** Instance of this class is accessible via {@code insight} variable * in theInsight
scripts registered to the instrument. */ public interface InsightAPI { /** ID of the instrument. Version {@code 1.1} has been released as * part of GraalVM 21.1.0 release. * * @return same value of {@linkInsight
#ID} - e.g. {@code "insight"} * @since 0.3 */String
id(); /** Version of the API. Version {@code 1.1} has been released as * part of GraalVM 21.1.0 release. * * @return same value of {@linkInsight
#VERSION} * @since 0.1 */String
version(); /** Marker interface for any handler. * @since 0.1 */ interface Handler { } interface SourceInfo { /** Name of the {@link OnSourceLoadedHandler#sourceLoaded}. * @return name of the loaded source * @since 0.1 */String
name(); /**Character
content of the {@link OnSourceLoadedHandler#sourceLoaded}. * @return content of the loaded source * @since 0.1 */String
characters(); /** Identification of this source's language. * @returnString
representing the language ID * @since 0.1 */String
language(); /** Mime type of this source. * @return given mime type or {@code null} * @since 0.1 */String
mimeType(); /** URI uniquely identifying the source. * @return the URI * @since 0.1 */String
uri(); } interface SourceSectionInfo { /** * Name of the enclosing function. * * @return the name of the enclosing function * @since 0.1 */String
name(); /** * Information about surrounding source. * * @return information about the surrounding source * @since 0.4 */ SourceInfo source(); /** * Characters of the location. * * @return the characters of this {@link OnEventHandler.Context} * @since 0.4 */String
characters(); /** * Line of this location. The same as {@link #startLine()}. * * @return line number counting from one * @since 0.4 */ int line(); /** * Staring line of this location. * * @return line number counting from one * @since 0.4 */ int startLine(); /** * Final line of this location. * * @return line number counting from one * @since 0.4 */ int endLine(); /** * Column of this location. The same as {@link #startColumn()}. * * @return column number counting from one * @since 0.4 */ int column(); /** * Starting column of this location. * * @return column number counting from one * @since 0.4 */ int startColumn(); /** * Final column of this location. * * @return column number counting from one * @since 0.4 */ int endColumn(); /** * Returns the 0-based index of the first character in this section. * Returns <code>0</code> for unavailable source * sections. * * @return the starting character index * @since 1.1 */ int charIndex(); /** * Returns the length of this section in characters. Returns * <code>0</code> for unavailable source * sections. * * @return the number of characters in the section * @since 1.1 */ int charEndIndex(); /** * Returns the index of the text position immediately following the last * character in the section. * Returns <code>0</code> for unavailable source sections. * * @return the end position of the section * @since 1.1 */ int charLength(); } @FunctionalInterface
interface OnSourceLoadedHandler extends Handler { /** Called when a new source is loaded into the system. * @param info information about the loaded source * @since 0.1 */ void sourceLoaded(SourceInfo info); } /** Register a handler to be notified when a source is loaded. * * @param event has to be {@code "source"} string * @param handler a callback that takes * {@link SourceInfo one argument} */ void on(String
event, OnSourceLoadedHandler handler); @FunctionalInterface
interface OnEventHandler extends Handler { interface Context extends SourceSectionInfo { /** The current return value to be returned unless * {@link #returnNow} is called. The only meaningful * values can be expected inside of {@link #on on("return", ...)} * handlers. * * @param frame object with variables provided * as a second parameter to {@link OnEventHandler#event event} * method * @return the current return value or {@code null}, * if not applicable * @since 0.7 */Object
returnValue(Map
<String
,Object
> frame); /** Immediatelly exits the current handler and returns to the * caller. Calling this method aborts execution of the current * handler. It bypasses language sematics and immediatelly * returns the provided value to the caller. If there are multiple * calls to {@code returnNow} (from different handlers) the * first call defines the return value. * * @param value the value to return to the caller * @since 0.7 * @see #returnValue(java.util.Map
) */ void returnNow(Object
value); /** Walks the stack at current execution point and iterates through * invocation frames and their local values. * * @param <T> type to return from the iterator * @param it iterator to call for each frame * (that is not {@linkSource
#isInternal() internal}) * @return first non-{@code null} value returned * from the {@code it} iterator or {@code null} * @since 1.0 */ <T> T iterateFrames(FramesIterator<T> it); } void event(Context ctx,Map
<String
,Object
> frame); } /** Iterator for the {@link OnEventHandler.Context#iterateFrames}. * @since 1.0 */ @FunctionalInterface
interface FramesIterator<T> { /** Called for each frame found on the stack. * * @param at location in the source code * @param frame access to local variables * @return {@code null} to continue iteration, non-{@code null} to * return immediatelly from the * {@link OnEventHandler.Context#iterateFrames} method. */ T onFrame(SourceSectionInfo at,Map
<String
,Object
> frame); } class OnConfig { public boolean expressions; public boolean statements; public boolean roots; /**String
with a regular expression to match name of functions. * Prior to version 0.6 this had to be a * {@code Function<String
,Boolean
>}. */ publicString
rootNameFilter; /* @since 0.4 */ publicPredicate
<SourceInfo> sourceFilter; /** *org.graalvm.tools.lsp.server.types.Location
in the source file. * @since 1.2 */ public OnConfigAt at; } class OnConfigAt { /** *String
with a regular expression to match source path. * Exactly one of this or {@link #sourceURI} is a mandatory property of * the `at` object. * @since 1.2 */ publicString
sourcePath; /** *String
representation of a source URI. * Exactly one of this or {@link #sourcePath} is a mandatory property of * the `at` object. * @since 1.2 */ publicString
sourceURI; /** * The line to match. * @since 1.2 */ publicObject
line; /** * The column to match. * @since 1.2 */ publicObject
column; } /** Register a handler on a particular elements in the source code. * * @param event one of {@code "enter"}, {@code "return"} strings * @param handler callback * {@link OnEventHandler#event function with two arguments} * @param config config object to identify locations to listen to */ void on(String
event, OnEventHandler handler, OnConfig config); @FunctionalInterface
interface OnCloseHandler extends Handler { void closed(); } /** Register on close handler. * * @param event must be {@code "close"} string * @param handler no args function to be notified when execution ends */ void on(String
event, OnCloseHandler handler); /** Unregisters a handler. * * @param event the event type to unregister from * @param handler the instance of handler registered * by one of the {@code on} methods * @since 0.2 */ void off(String
event, Handler handler); }