com.oracle.truffle.api.instrumentation

Class TruffleInstrument.Env

java.lang.Object

com.oracle.truffle.api.instrumentation.TruffleInstrument.Env

Enclosing class:

TruffleInstrument

public static final class TruffleInstrument.Env
extends Object

Access to instrumentation services as well as input, output, and error streams.

Since:

0.12

Method Summary

Modifier and Type	Method and Description
OutputStream	err() Standard error writer for Engine this instrument is being executed in.
Iterable<Scope>	findLocalScopes(Node node, Frame frame) Find a list of local scopes enclosing the given node.
Iterable<Scope>	findTopScopes(String languageId) Find a list of top scopes of a language.
Instrumenter	getInstrumenter() Returns the instrumenter which lets you instrument guest language ASTs.
Map<String,InstrumentInfo>	getInstruments() Returns a map instrument id to instrument info of all instruments that are installed in the environment.
LanguageInfo	getLanguageInfo(Class<? extends TruffleLanguage<?>> languageClass) Returns the language info for a given language class if available.
Map<String,LanguageInfo>	getLanguages() Returns a map language id to language info of all languages that are installed in the environment.
Object	getLanguageView(LanguageInfo language, Object value) Wraps the provided value to provide language specific information for primitive and foreign values.
TruffleLogger	getLogger(Class<?> forClass) Find or create an engine bound logger for an instrument.
TruffleLogger	getLogger(String loggerName) Find or create an engine bound logger for an instrument.
org.graalvm.options.OptionValues	getOptions() Returns option values for the options described in TruffleInstrument.getOptionDescriptors().
Object	getPolyglotBindings() Returns the polyglot scope - symbols explicitly exported by languages.
Object	getScopedView(LanguageInfo language, Node location, Frame frame, Object value) Returns the scoped view of a value for a location in the AST.
TruffleFile	getTruffleFile(String path) Returns a TruffleFile for given path.
TruffleFile	getTruffleFile(URI uri) Returns a TruffleFile for given URI.
InputStream	in() Input associated with Engine this instrument is being executed in.
boolean	isEngineRoot(RootNode root) Returns true if the given root node is considered an engine evaluation root for the current execution context.
<S> S	lookup(InstrumentInfo instrument, Class<S> type) Returns an additional service provided by this instrument, specified by type.
<S> S	lookup(LanguageInfo language, Class<S> type) Queries a language implementation for a special service.
OutputStream	out() Standard output writer for Engine this instrument is being executed in.
CallTarget	parse(Source source, String... argumentNames) Evaluates source of (potentially different) language using the current context.The names of arguments are parameters for the resulting {#link CallTarget} that allow the source to reference the actual parameters passed to CallTarget.call(java.lang.Object...).
ExecutableNode	parseInline(Source source, Node node, MaterializedFrame frame) Parses source snippet of the node's language at the provided node location.
void	registerService(Object service) Registers additional service.
void	setAsynchronousStackDepth(int depth) Request for languages to provide stack frames of scheduled asynchronous execution.
org.graalvm.polyglot.io.MessageEndpoint	startServer(URI uri, org.graalvm.polyglot.io.MessageEndpoint server) Start a server at the provided URI via the MessageTransport service.

Methods inherited from class java.lang.Object

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

Method Detail

getInstrumenter

public Instrumenter getInstrumenter()

Returns the instrumenter which lets you instrument guest language ASTs.

Since:

0.12

See Also:

Instrumenter

in

public InputStream in()

Input associated with Engine this instrument is being executed in.

Returns:

reader, never null

Since:

0.12

out

public OutputStream out()

Standard output writer for Engine this instrument is being executed in.

Returns:

writer, never null

Since:

0.12

err

public OutputStream err()

Standard error writer for Engine this instrument is being executed in.

Returns:

writer, never null

Since:

0.12

startServer

public org.graalvm.polyglot.io.MessageEndpoint startServer(URI uri,
                                                           org.graalvm.polyglot.io.MessageEndpoint server)
                                                    throws IOException,
                                                           org.graalvm.polyglot.io.MessageTransport.VetoException

Start a server at the provided URI via the MessageTransport service. Before an instrument creates a server endpoint for a message protocol, it needs to check the result of this method. When a virtual message transport is available, it blocks until a client connects and MessageEndpoint representing the peer endpoint is returned. Those endpoints need to be used instead of a direct creation of a server socket. If no virtual message transport is available at that URI, null is returned and the instrument needs to set up the server itself.

When MessageTransport.VetoException is thrown, the server creation needs to be abandoned.

This method can be called concurrently from multiple threads. However, the MessageEndpoint ought to be called on one thread at a time, unless you're sure that the particular implementation can handle concurrent calls. The same holds true for the returned endpoint, it's called synchronously.

Parameters:

uri - the URI of the server endpoint

server - the handler of messages at the server side

Returns:

an implementation of MessageEndpoint call back representing the client side, or null when no virtual transport is available

Throws:

MessageTransport.VetoException - if creation of a server at that URI is not allowed

IOException

Since:

19.0

registerService

public void registerService(Object service)

Registers additional service. This method can be called multiple time, but only during initialization of the instrument. These services are made available to users via Instrument.lookup(java.lang.Class<T>) query method. This method can only be called from TruffleInstrument.onCreate(com.oracle.truffle.api.instrumentation.TruffleInstrument.Env) method - then the services are collected and cannot be changed anymore.

Parameters:

service - a service to be returned from associated Instrument.lookup(java.lang.Class<T>)

Throws:

IllegalStateException - if the method is called later than from TruffleInstrument.onCreate(com.oracle.truffle.api.instrumentation.TruffleInstrument.Env) method

Since:

0.12

lookup

public <S> S lookup(LanguageInfo language,
                    Class<S> type)

Queries a language implementation for a special service. The services can be provided by the language by directly implementing them when subclassing TruffleLanguage. The truffle language needs to be entered on the current Thread otherwise an AssertionError is thrown.

Type Parameters:

S - the requested type

Parameters:

language - identification of the language to query

type - the class of the requested type

Returns:

the registered service or null if none is found

Since:

0.26

lookup

public <S> S lookup(InstrumentInfo instrument,
                    Class<S> type)

Returns an additional service provided by this instrument, specified by type. If an instrument is not enabled, it will be enabled automatically by requesting a supported service. If the instrument does not provide a service for a given type it will not be enabled automatically. An IllegalArgumentException is thrown if a service is looked up from the current instrument.

Type Parameters:

S - the requested type

Parameters:

instrument - identification of the instrument to query

type - the class of the requested type

Returns:

the registered service or null if none is found

Since:

0.26

getLanguages

public Map<String,LanguageInfo> getLanguages()

Returns a map language id to language info of all languages that are installed in the environment.

Since:

0.26

getInstruments

public Map<String,InstrumentInfo> getInstruments()

Returns a map instrument id to instrument info of all instruments that are installed in the environment.

Since:

0.26

getOptions

public org.graalvm.options.OptionValues getOptions()

Returns option values for the options described in TruffleInstrument.getOptionDescriptors(). The returned options are never null.

Since:

0.27

parse

public CallTarget parse(Source source,
                        String... argumentNames)
                 throws IOException

Evaluates source of (potentially different) language using the current context.The names of arguments are parameters for the resulting {#link CallTarget} that allow the source to reference the actual parameters passed to CallTarget.call(java.lang.Object...).

Parameters:

source - the source to evaluate

argumentNames - the names of CallTarget.call(java.lang.Object...) arguments that can be referenced from the source

Returns:

the call target representing the parsed result

Throws:

IOException - if the parsing or evaluation fails for some reason

SecurityException

Since:

0.12

parseInline

public ExecutableNode parseInline(Source source,
                                  Node node,
                                  MaterializedFrame frame)

Parses source snippet of the node's language at the provided node location. The result is an AST fragment represented by ExecutableNode that accepts frames valid at the provided node location, or null when inline parsing is not supported by the language.

Parameters:

source - a source snippet to parse at the provided node location

node - a context location where the source is parsed at, must not be null

frame - a frame location where the source is parsed at, can be null

Returns:

the executable fragment representing the parsed result, or null

Since:

0.31

getTruffleFile

public TruffleFile getTruffleFile(String path)

Returns a TruffleFile for given path. This must be called on a context thread only.

Parameters:

path - the absolute or relative path to create TruffleFile for

Returns:

TruffleFile

Since:

19.0

getTruffleFile

public TruffleFile getTruffleFile(URI uri)

Returns a TruffleFile for given URI. This must be called on a context thread only.

Parameters:

uri - the URI to create TruffleFile for

Returns:

TruffleFile

Since:

19.0

isEngineRoot

public boolean isEngineRoot(RootNode root)

Returns true if the given root node is considered an engine evaluation root for the current execution context. Multiple such root nodes can appear on stack frames returned by TruffleRuntime.iterateFrames(com.oracle.truffle.api.frame.FrameInstanceVisitor). A debugger implementation might use this information to hide stack frames of other engines.

Parameters:

root - the root node to check

Returns:

true if engine root else false

Since:

0.17

setAsynchronousStackDepth

public void setAsynchronousStackDepth(int depth)

Request for languages to provide stack frames of scheduled asynchronous execution. Languages might not provide asynchronous stack frames by default for performance reasons. At most depth asynchronous stack frames are asked for. When multiple instruments call this method, the languages get a maximum depth of these calls and may therefore provide longer asynchronous stacks than requested. Also, languages may provide asynchronous stacks if it's of no performance penalty, or if requested by other options.

Asynchronous stacks can then be accessed via TruffleStackTrace.getAsynchronousStackTrace(CallTarget, Frame).

Parameters:

depth - the requested stack depth, 0 means no asynchronous stack frames are required.

Since:

20.1.0

See Also:

TruffleStackTrace.getAsynchronousStackTrace(CallTarget, Frame)

getLanguageInfo

public LanguageInfo getLanguageInfo(Class<? extends TruffleLanguage<?>> languageClass)

Returns the language info for a given language class if available. Language classes are typically obtained by invoking the InteropLibrary.getLanguage(Object) message. Throws an IllegalArgumentException if the provided language is not registered. Note that languages may be returned that are not contained in TruffleInstrument.Env.getLanguages(). For example, values originating from the embedder like Java classes or polyglot proxies.

Parameters:

languageClass - the language class to convert

Returns:

the associated language info

Throws:

IllegalArgumentException - if the language class is not valid.

Since:

20.1

getLanguageView

public Object getLanguageView(LanguageInfo language,
                              Object value)

Wraps the provided value to provide language specific information for primitive and foreign values. A typical implementation of a given language for this method does the following:

• Return the current language as their associated language.
• Provide a language specific display string for primitive and foreign values.
• Return a language specific metaobject primitive or foreign values.
• Add members to the object that would implicitly be available for all objects. For example, any JavaScript object is expected to have a prototype member. Foreign objects, even if they do not have such a member, are interpreted as if they have.

Parameters:

language - the language to provide the view for

value - the value to language specific information for.

Since:

20.1

See Also:

TruffleLanguage.getLanguageView(Object, Object)

getScopedView

public Object getScopedView(LanguageInfo language,
                            Node location,
                            Frame frame,
                            Object value)

Returns the scoped view of a value for a location in the AST. Allows the language to augment the perspective that tools have on values depending on location and frame. This may be useful to apply local specific visibility and accessibility rules. A typical implementation of this method may do the following:

• Apply visiblity and scoping rules to the value hiding or removing members from the object.
• Add or remove implicit members that are only available within this source location.

The provided language must match the language of the root node of the location provided. The frame must have the same FrameDescriptor associated as the RootNode of the provided location. The provided location must be instrumentable. If any of these pre-conditions are violated then an IllegalArgumentException is thrown.

If a value is not yet associated with the provided language, then a language view will be requested implicitly. Only interop messages should be used on the result of this method.

Parameters:

language - the language must match the language

location - the location to provide scope for. Never null and returns true for InstrumentableNode.isInstrumentable(). E.g. any location observed using EventContext.getInstrumentedNode().

frame - the frame of the current activation of the parent RootNode.

value - the value to provide scope information for.

Since:

20.1

See Also:

TruffleLanguage.getScopedView(Object, Node, Frame, Object)

getPolyglotBindings

public Object getPolyglotBindings()

Returns the polyglot scope - symbols explicitly exported by languages. The polyglot bindings of the current entered context are returned.

Returns:

an interop object having the symbol names as properties

Since:

20.1

findLocalScopes

public Iterable<Scope> findLocalScopes(Node node,
                                       Frame frame)

Find a list of local scopes enclosing the given node. The scopes contain variables that are valid at the provided node and that have a relation to it. Unless the node is in a global scope, it is expected that there is at least one scope provided, that corresponds to the enclosing function. Global top scopes are provided by TruffleInstrument.Env.findTopScopes(java.lang.String). The iteration order corresponds with the scope nesting, from the inner-most to the outer-most.

Scopes may depend on the information provided by the frame.
Lexical scopes are returned when frame argument is null.

Parameters:

node - a node to get the enclosing scopes for. The node needs to be inside a RootNode associated with a language.

frame - The current frame the node is in, or null for lexical access when the program is not running, or is not suspended at the node's location.

Returns:

an Iterable providing list of scopes from the inner-most to the outer-most.

Since:

0.30

See Also:

TruffleLanguage.findLocalScopes(java.lang.Object, com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.frame.Frame)

findTopScopes

public Iterable<Scope> findTopScopes(String languageId)

Find a list of top scopes of a language. The iteration order corresponds with the scope nesting, from the inner-most to the outer-most.

Parameters:

languageId - a language id.

Returns:

a list of top scopes, can be empty when no top scopes are provided by the language

Since:

0.30

See Also:

TruffleLanguage.findTopScopes(java.lang.Object)

getLogger

public TruffleLogger getLogger(String loggerName)

Find or create an engine bound logger for an instrument. When a logging is required from a thread which entered a context the context's logging handler and options are used. Otherwise the engine's logging handler and options are used.

If a logger with given name already exists it's returned, otherwise a new logger is created.

Unlike loggers created by TruffleLogger.getLogger loggers created by this method are bound to engine, there may be more logger instances having the same name but each bound to different engine instance. Instruments should never store the returned logger into a static fields. A new logger must be always created in onCreate method.

Parameters:

loggerName - the the name of a TruffleLogger, if a loggerName is null or empty a root logger for language or instrument is returned

Returns:

a TruffleLogger

Since:

19.0

getLogger

public TruffleLogger getLogger(Class<?> forClass)

Find or create an engine bound logger for an instrument. The engine bound loggers can be used by threads executing without any current context. When a logging is required from a thread which entered a context the context's logging handler and options are used. Otherwise the engine's logging handler and options are used.

If a logger for the class already exists it's returned, otherwise a new logger is created.

Unlike loggers created by TruffleLogger.getLogger loggers created by this method are bound to engine, there may be more logger instances having the same name but each bound to different engine instance. Instruments should never store the returned logger into a static fields. A new logger must be always created in onCreate method.

Parameters:

forClass - the Class to create a logger for

Returns:

a TruffleLogger

Throws:

NullPointerException - if forClass is null

Since:

19.0