public final class Insight extends Object
Insight.ID:
finaland thenEngineengine = context.getEngine();Instrumentinstrument = engine.getInstruments().get("insight");Function<Source,AutoCloseable> access = instrument.lookup(Function.class);AutoCloseablehandle = 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 the Insight scripts registered to the instrument.
*/
public interface InsightAPI {
/** ID of the instrument. Version {@code 0.5} has been released as
* part of GraalVM 20.1 release.
*
* @return same value of {@link Insight#ID} - e.g. {@code "insight"}
* @since 0.3
*/
String id();
/** Version of the API. Version {@code 0.1} has been released as
* part of GraalVM 19.3.0 release.
*
* @return same value of {@link Insight#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.
* @return String 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();
}
@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 {
/** 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 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();
/** 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);
}
void event(Context ctx, 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>}.
*/
public String rootNameFilter;
/* @since 0.4 */
public Predicate<SourceInfo> sourceFilter;
}
/** 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);
}
public static final String ID
"insight". Use it to obtain access to an
Insight instruments inside of your Engine:
finalEngineengine = context.getEngine();Instrumentinstrument = engine.getInstruments().get("insight");Function<Source,AutoCloseable> access = instrument.lookup(Function.class);AutoCloseablehandle = access.apply(agentSrc);
public static final String VERSION
insight
reference:
/** Instance of this class is accessible via {@code insight} variable
* in the Insight scripts registered to the instrument.
*/
public interface InsightAPI {
/** ID of the instrument. Version {@code 0.5} has been released as
* part of GraalVM 20.1 release.
*
* @return same value of {@link Insight#ID} - e.g. {@code "insight"}
* @since 0.3
*/
String id();
/** Version of the API. Version {@code 0.1} has been released as
* part of GraalVM 19.3.0 release.
*
* @return same value of {@link Insight#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.
* @return String 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();
}
@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 {
/** 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 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();
/** 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);
}
void event(Context ctx, 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>}.
*/
public String rootNameFilter;
/* @since 0.4 */
public Predicate<SourceInfo> sourceFilter;
}
/** 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);
}