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 PolyglotEngine this instrument is being executed in.
Object	findMetaObject(Node node, Object value) Find a meta-object of a value, if any.
SourceSection	findSourceLocation(Node node, Object value) Find a source location where a value is declared, if any.
Instrumenter	getInstrumenter() Returns the instrumenter which lets you instrument guest language ASTs.
Map<String,InstrumentInfo>	getInstruments() Returns a map mime-type to instrument identifier of all instruments that are installed in the environment.
Map<String,LanguageInfo>	getLanguages() Returns a map mime-type to language identifier of all languages that are installed in the environment.
InputStream	in() Input associated with PolyglotEngine 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 PolyglotEngine 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...).
void	registerService(Object service) Registers additional service.
String	toString(Node node, Object value) Uses the original language of the node to print a string representation of this value.

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 PolyglotEngine this instrument is being executed in.

Returns:

reader, never null

Since:

0.12

out

public OutputStream out()

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

Returns:

writer, never null

Since:

0.12

err

public OutputStream err()

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

Returns:

writer, never null

Since:

0.12

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 PolyglotRuntime.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 PolyglotRuntime.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.

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 mime-type to language identifier of all languages that are installed in the environment.

Since:

0.26

getInstruments

public Map<String,InstrumentInfo> getInstruments()

Returns a map mime-type to instrument identifier of all instruments that are installed in the environment.

Since:

0.26

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

Since:

0.12

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

toString

public String toString(Node node,
                       Object value)

Uses the original language of the node to print a string representation of this value. The behavior of this method is undefined if a type unknown to the language is passed as value.

Parameters:

node - a node

value - a known value of that language

Returns:

a human readable string representation of the value.

Since:

0.17

findMetaObject

public Object findMetaObject(Node node,
                             Object value)

Find a meta-object of a value, if any. The meta-object represents a description of the object, reveals it's kind and it's features. Some information that a meta-object might define includes the base object's type, interface, class, methods, attributes, etc. When no meta-object is known, null is returned.

Parameters:

node - a node

value - a value to find the meta-object of

Returns:

the meta-object, or null

Since:

0.22

findSourceLocation

public SourceSection findSourceLocation(Node node,
                                        Object value)

Find a source location where a value is declared, if any.

Parameters:

node - a node

value - a value to get the source location for

Returns:

a source location of the object, or null

Since:

0.22