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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`OutputStream`	`err()` Standard error writer for `Engine` this `instrument` is being executed in.
`LanguageInfo`	`findLanguage(Object value)` Find a language that created the value, if any.
`Iterable<Scope>`	`findLocalScopes(Node node, Frame frame)` Find a list of local scopes enclosing the given `node`.
`Object`	`findMetaObject(LanguageInfo language, Object value)` Uses the provided language to find a meta-object of a value, if any.
`SourceSection`	`findSourceLocation(LanguageInfo language, Object value)` Uses the provided language to find a source location where a value is declared, if any.
`Iterable<Scope>`	`findTopScopes(String languageId)` Find a list of top scopes of a language.
`Map<String,? extends Object>`	`getExportedSymbols()` Returns the polyglot scope - symbols explicitly exported by languages.
`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.
`Map<String,LanguageInfo>`	`getLanguages()` Returns a map `language id` to `language info` of all languages that are installed in the environment.
`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 `TruffleLanguage.getOptionDescriptors()`.
`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.
`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.
`String`	`toString(LanguageInfo language, Object value)` Uses the provided language 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 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 TruffleLanguage.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
    
    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
  - toString
```
public String toString(LanguageInfo language,
                       Object value)
```
    Uses the provided language 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 a value.
    
    Parameters:
    
    language - a language
    
    value - a known value of that language, must be an interop type (i.e. either implementing TruffleObject or be a primitive value)
    
    Returns:
    
    a human readable string representation of the value.
    
    Since:
    
    0.27
    
    See Also:
    
    TruffleInstrument.Env.findLanguage(java.lang.Object)
  - findMetaObject
```
public Object findMetaObject(LanguageInfo language,
                             Object value)
```
    Uses the provided language to 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. For the best results, use the value's language, if any.
    
    Parameters:
    
    language - a language
    
    value - a value to find the meta-object of, must be an interop type (i.e. either implementing TruffleObject or be a primitive value)
    
    Returns:
    
    the meta-object, or null
    
    Since:
    
    0.27
    
    See Also:
    
    TruffleInstrument.Env.findLanguage(java.lang.Object)
  - findSourceLocation
```
public SourceSection findSourceLocation(LanguageInfo language,
                                        Object value)
```
    Uses the provided language to find a source location where a value is declared, if any. For the best results, use the value's language, if any.
    
    Parameters:
    
    language - a language
    
    value - a value to get the source location for, must be an interop type (i.e. either implementing TruffleObject or be a primitive value)
    
    Returns:
    
    a source location of the object, or null
    
    Since:
    
    0.27
    
    See Also:
    
    TruffleInstrument.Env.findLanguage(java.lang.Object)
  - findLanguage
```
public LanguageInfo findLanguage(Object value)
```
    Find a language that created the value, if any. This method will return null for values representing a primitive value, or objects that are not associated with any language.
    
    Parameters:
    
    value - the value to find a language of
    
    Returns:
    
    the language, or null when there is no language associated with the value.
    
    Since:
    
    0.27
  - getExportedSymbols
```
public Map<String,? extends Object> getExportedSymbols()
```
    Returns the polyglot scope - symbols explicitly exported by languages.
    
    Returns:
    
    a read-only map of symbol names and their values
    
    Since:
    
    0.30
  - 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

Class TruffleInstrument.Env

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getInstrumenter

in

out

err

startServer

registerService

lookup

lookup

getLanguages

getInstruments

getOptions

parse

parseInline

getTruffleFile

getTruffleFile

isEngineRoot

toString

findMetaObject

findSourceLocation

findLanguage

getExportedSymbols

findLocalScopes

findTopScopes

getLogger

getLogger