Class TruffleInstrument.Env
- Enclosing class:
TruffleInstrument
- Since:
- 0.12
-
Method Summary
Modifier and TypeMethodDescriptionlong
calculateContextHeapSize
(TruffleContext truffleContext, long stopAtBytes, AtomicBoolean cancelled) Returns heap memory size retained by a polyglot context.createSystemThread
(Runnable runnable) Creates a new thread designed to process instrument tasks in the background.createSystemThread
(Runnable runnable, ThreadGroup threadGroup) Creates a new thread designed to process instrument tasks in the background.err()
Standard error writer forEngine
thisinstrument
is being executed in.Returns the enteredTruffleContext
ornull
when no context is entered.Returns the instrumenter which lets you instrument guest language ASTs.Returns a mapinstrument id
toinstrument info
of all instruments that are installed in the environment.getInternalResource
(Class<? extends InternalResource> resource) Returns theTruffleFile
representing the target directory of an internal resource.getInternalResource
(String resourceId) Returns theTruffleFile
representing the target directory of an internal resource.getLanguageInfo
(Class<? extends TruffleLanguage<?>> languageClass) Returns thelanguage info
for a given language class if available.Returns a maplanguage id
tolanguage info
of all languages that are installed in the environment.getLanguageView
(LanguageInfo language, Object value) Wraps the provided value to provide language specific information for primitive and foreign values.Find or create an engine bound logger for an instrument.Find or create an engine bound logger for an instrument.Returns the context independent option values for the options described inTruffleInstrument.getOptionDescriptors()
.getOptions
(TruffleContext context) Returns the context specific option values for the options described inTruffleInstrument.getContextOptionDescriptors()
andTruffleInstrument.getOptionDescriptors()
.Returns the polyglot scope - symbols explicitly exported by languages.Returns the engine'sSandboxPolicy
.getScope
(LanguageInfo language) Provides top scope object of the language, if any.getTruffleFile
(TruffleContext context, String path) Returns aTruffleFile
for given path andcontext
.getTruffleFile
(TruffleContext context, URI uri) getTruffleFile
(String path) Deprecated.since 23.0.getTruffleFile
(URI uri) Deprecated.since 23.0.in()
Input associated withEngine
thisinstrument
is being executed in.boolean
isEngineRoot
(RootNode root) Returnstrue
if the given root node is considered an engine evaluation root for the current execution context.boolean
isSameFrame
(RootNode root, Frame frame1, Frame frame2) Tests if two frames are the same.<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 alanguage implementation
for a special service.out()
Standard output writer forEngine
thisinstrument
is being executed in.Evaluates source of (potentially different) language using the current context.The names of arguments are parameters for the resulting {#link CallTarget} that allow thesource
to reference the actual parameters passed toCallTarget.call(java.lang.Object...)
.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.startServer
(URI uri, MessageEndpoint server) Start a server at the provided URI via theMessageTransport
service.submitThreadLocal
(TruffleContext context, Thread[] threads, ThreadLocalAction action) Submits a thread local action to be performed at the next guest language safepoint on a provided set of threads, once for each thread.
-
Method Details
-
getInstrumenter
Returns the instrumenter which lets you instrument guest language ASTs.- Since:
- 0.12
- See Also:
-
in
Input associated withEngine
thisinstrument
is being executed in.- Returns:
- reader, never
null
- Since:
- 0.12
-
out
Standard output writer forEngine
thisinstrument
is being executed in.- Returns:
- writer, never
null
- Since:
- 0.12
-
err
Standard error writer forEngine
thisinstrument
is being executed in.- Returns:
- writer, never
null
- Since:
- 0.12
-
startServer
public MessageEndpoint startServer(URI uri, MessageEndpoint server) throws IOException, MessageTransport.VetoException Start a server at the provided URI via theMessageTransport
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 andMessageEndpoint
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 endpointserver
- the handler of messages at the server side- Returns:
- an implementation of
MessageEndpoint
call back representing the client side, ornull
when no virtual transport is available - Throws:
MessageTransport.VetoException
- if creation of a server at that URI is not allowedIOException
- Since:
- 19.0
-
registerService
Registers additional service. This method can be called multiple time, but only duringinitialization of the instrument
. These services are made available to users viaInstrument.lookup(java.lang.Class<T>)
query method. This method can only be called fromTruffleInstrument.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 associatedInstrument.lookup(java.lang.Class<T>)
- Throws:
IllegalStateException
- if the method is called later than fromTruffleInstrument.onCreate(com.oracle.truffle.api.instrumentation.TruffleInstrument.Env)
method- Since:
- 0.12
-
lookup
Queries alanguage implementation
for a special service. The services can be provided by the language by directly implementing them when subclassingTruffleLanguage
. The truffle language needs to be entered on the current Thread otherwise anAssertionError
is thrown.- Type Parameters:
S
- the requested type- Parameters:
language
- identification of the language to querytype
- the class of the requested type- Returns:
- the registered service or
null
if none is found - Since:
- 0.26
-
lookup
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. AnIllegalArgumentException
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 querytype
- the class of the requested type- Returns:
- the registered service or
null
if none is found - Since:
- 0.26
-
getLanguages
Returns a maplanguage id
tolanguage info
of all languages that are installed in the environment.- Since:
- 0.26
-
getInstruments
Returns a mapinstrument id
toinstrument info
of all instruments that are installed in the environment.- Since:
- 0.26
-
getOptions
Returns the context independent option values for the options described inTruffleInstrument.getOptionDescriptors()
. The returned options are nevernull
.- Since:
- 0.27
- See Also:
-
getOptions
Returns the context specific option values for the options described inTruffleInstrument.getContextOptionDescriptors()
andTruffleInstrument.getOptionDescriptors()
. Instrument context options can be different for each TruffleContext, whereas regular options cannot.- Since:
- 20.3
- See Also:
-
parse
Evaluates source of (potentially different) language using the current context.The names of arguments are parameters for the resulting {#link CallTarget} that allow thesource
to reference the actual parameters passed toCallTarget.call(java.lang.Object...)
.- Parameters:
source
- the source to evaluateargumentNames
- the names ofCallTarget.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 reasonSecurityException
- Since:
- 0.12
-
parseInline
Parses source snippet of the node's language at the provided node location. The result is an AST fragment represented byExecutableNode
that accepts frames valid at the provided node location, ornull
when inline parsing is not supported by the language.- Parameters:
source
- a source snippet to parse at the provided node locationnode
- a context location where the source is parsed at, must not benull
frame
- a frame location where the source is parsed at, can benull
- Returns:
- the executable fragment representing the parsed result, or
null
- Since:
- 0.31
-
getTruffleFile
Deprecated.since 23.0. UsegetTruffleFile(TruffleContext, String)
.Returns aTruffleFile
for given path. This must be called on a context thread only.- Parameters:
path
- the absolute or relative path to createTruffleFile
for- Returns:
TruffleFile
- Since:
- 19.0
-
getTruffleFile
Deprecated.since 23.0. UsegetTruffleFile(TruffleContext, URI)
.Returns aTruffleFile
for givenURI
. This must be called on a context thread only.- Parameters:
uri
- theURI
to createTruffleFile
for- Returns:
TruffleFile
- Since:
- 19.0
-
getTruffleFile
Returns aTruffleFile
for given path andcontext
.- Parameters:
context
- theTruffleContext
, ornull
to use a current entered context.path
- the absolute or relative path to createTruffleFile
for- Returns:
TruffleFile
- Throws:
UnsupportedOperationException
- when theFileSystem
supports onlyURI
IllegalArgumentException
- if thepath
string cannot be converted to aPath
- Since:
- 23.0
-
getTruffleFile
- Parameters:
context
- theTruffleContext
, ornull
to use a current entered context.uri
- theURI
to createTruffleFile
for- Returns:
TruffleFile
- Throws:
UnsupportedOperationException
- whenURI
scheme is not supportedIllegalArgumentException
- if preconditions on theuri
do not hold.FileSystemNotFoundException
- is the file system, identified by theuri
, does not exist and cannot be created automatically- Since:
- 23.0
-
getEnteredContext
Returns the enteredTruffleContext
ornull
when no context is entered.- Since:
- 20.3
-
isEngineRoot
Returnstrue
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 byTruffleRuntime.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 elsefalse
- 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 mostdepth
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 viaTruffleStackTrace.getAsynchronousStackTrace(CallTarget, Frame)
.- Parameters:
depth
- the requested stack depth, 0 means no asynchronous stack frames are required.- Since:
- 20.1.0
- See Also:
-
getLanguageInfo
Returns thelanguage info
for a given language class if available. Language classes are typically obtained by invoking theInteropLibrary.getLanguage(Object)
message. Throws anIllegalArgumentException
if the provided language is not registered. Note that languages may be returned that are not contained ingetLanguages()
. For example, values originating from the embedder like Java classes orpolyglot 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
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 forvalue
- the value to language specific information for.- Since:
- 20.1
- See Also:
- Return the current language as their associated
-
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
-
getScope
Provides top scope object of the language, if any. Uses the current context to find the language scope associated with. The returned object is aninterop scope object
, ornull
.- Parameters:
language
- a language- Returns:
- the top scope, or
null
if the language does not support such concept - Since:
- 20.3
- See Also:
-
getInternalResource
public TruffleFile getInternalResource(Class<? extends InternalResource> resource) throws IOException Returns theTruffleFile
representing the target directory of an internal resource. The internal resource is guaranteed to be fullyInternalResource.unpackFiles(InternalResource.Env, Path)
unpacked} before this method returns. When this method is called for the first time and the resource is not cached than the resource will be unpacked. Unpacking an internal resource can be an expensive operation, but the implementation makes sure that unpacked internal resources are cached.The returned
TruffleFile
will only grant read-only access to the target directory, but access is provided even if IO access is disabled.On a HotSpot VM the internal resource is typically cached in the user directory, so unpacking would be repeated once per operating system user. When the language was compiled using native-image internal resources are unpacked at native-image compile time and stored relative to the native-image.
The caller thread must be entered in a context.
- Parameters:
resource
- the resource class to load- Throws:
IllegalArgumentException
- ifresource
is not associated with this instrumentIOException
- in case of IO error- Since:
- 23.1
-
getInternalResource
Returns theTruffleFile
representing the target directory of an internal resource. Unlike thegetInternalResource(Class)
, this method can be used for optional resources whose classes may not exist at runtime. In this case the optional resource must be unpacked at build time, seeEngine.copyResources(Path, String...)
. If the resource with the specifiedresourceId
is not associated to this instrument, the function returnsnull
.- Parameters:
resourceId
- unique id of the resource to be loaded- Returns:
- internal resource directory or
null
if resource with theresourceId
is not associated with this instrument - Throws:
IOException
- in case of IO error- Since:
- 23.1
- See Also:
-
getLogger
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 inonCreate
method.- Parameters:
loggerName
- the the name of aTruffleLogger
, if aloggerName
is null or empty a root logger for language or instrument is returned- Returns:
- a
TruffleLogger
- Since:
- 19.0
-
getLogger
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 inonCreate
method.- Parameters:
forClass
- theClass
to create a logger for- Returns:
- a
TruffleLogger
- Throws:
NullPointerException
- ifforClass
is null- Since:
- 19.0
-
isSameFrame
Tests if two frames are the same. This method is mainly used by instruments in case ofyield
of the execution and later resume. Frame comparison is used to match the particular yielded and resumed execution. The frames must correspond to the root.- Since:
- 24.0
-
calculateContextHeapSize
public long calculateContextHeapSize(TruffleContext truffleContext, long stopAtBytes, AtomicBoolean cancelled) Returns heap memory size retained by a polyglot context.- Parameters:
truffleContext
- specifies the polyglot context for which retained size is calculated.stopAtBytes
- when the calculated size exceeds stopAtBytes, calculation is stopped and only size calculated up to that point is returned, i.e., if the retained size is greater than stopAtBytes, a value greater than stopAtBytes will be returned, not the total retained size which might be much greater.cancelled
- when cancelled returns true, calculation is cancelled andCancellationException
is thrown. The message of the exception specifies the number of bytes calculated up to that point.- Returns:
- calculated heap memory size retained by the specified polyglot context, or a value greater than stopAtBytes if the calculated size is greater than stopAtBytes.
- Throws:
UnsupportedOperationException
- in case heap size calculation is not supported on current runtime.CancellationException
- in case the heap size calculation is cancelled based on the cancelled parameter. The message of the exception specifies the number of bytes calculated up to that point.- Since:
- 21.1
-
submitThreadLocal
public Future<Void> submitThreadLocal(TruffleContext context, Thread[] threads, ThreadLocalAction action) Submits a thread local action to be performed at the next guest language safepoint on a provided set of threads, once for each thread. If the threads array isnull
then the thread local action will be performed on all alive threads. The submitted actions are processed in the same order as they are submitted in. The action can be synchronous or asynchronous, side-effecting or non-sideeffecting. Please seeThreadLocalAction
for details.It is ensured that a thread local action will get processed as long as the thread stays active for this context. If a thread becomes inactive before the action can get processed then the action will not be performed for this thread. If a thread becomes active while the action is being processed then the action will be performed for that thread as long as the thread filter includes the thread or
null
was passed. Already started synchronous actions will block on activation of a new thread. If the synchronous action was not yet started on any thread, then the synchronous action will also be performed for the newly activated thread.The method returns a
Future
instance that allows to wait for the thread local action to complete or to cancel a currently performed event.Example Usage:
Env env; // supplied by TruffleInstrument TruffleContext context; // supplied by ContextsListener env.submitThreadLocal(context, null, new ThreadLocalAction(true, true) { @Override protected void perform(Access access) { // perform action } });
By default thread-local actions are executed once per configured thread and do not repeat themselves. If a ThreadLocalAction is configured to be
recurring
then the action will automatically be rescheduled in the same configuration until it iscancelled
. For recurring actions, an invocation ofFuture.get()
will only wait for the first action to to be performed.Future.isDone()
will returntrue
only if the action was canceled. Canceling a recurring action will result in the current event being canceled and no further events being submitted. Using recurring events should be preferred over submitting the event again for the current thread while performing the thread-local action as recurring events are also resubmitted in case all threads leave and later reenter.If the thread local action future needs to be waited on and this might be prone to deadlocks the
blocking API
can be used to allow other thread local actions to be processed while the current thread is waiting. The returnedFuture.get()
method can be used asTruffleSafepoint.Interruptible
. If the supplied context is already closed, the method returns a completedFuture
.- Parameters:
context
- the context in which the action should be performed. Nonnull
.threads
- the threads to execute the action on.null
for all threadsaction
- the action to perform on that thread.- Since:
- 21.1
- See Also:
-
createSystemThread
Creates a new thread designed to process instrument tasks in the background. SeecreateSystemThread(Runnable, ThreadGroup)
for a detailed description of the parameters.- Since:
- 22.3
- See Also:
-
createSystemThread
Creates a new thread designed to process instrument tasks in the background. The created thread cannot enter the context, if it tries anIllegalStateException
is thrown. Creating or terminating a system thread does not notify languages orThreadsListener
s. Creating a system thread does not cause a transition to multi-threaded access.It is recommended to set an
uncaught exception handler
for the created thread. For example the thread can throw an uncaught exception if the engine is closed before the thread is started.The instrument that created and started the thread is responsible to stop and join it during the
onDispose
, otherwise anIllegalStateException
is thrown. It's not safe to use theExecutorService.awaitTermination(long, java.util.concurrent.TimeUnit)
to detect Thread termination as the system thread may be cancelled before executing the executor worker.
A typical implementation looks like:class SystemThreadInstrument extends TruffleInstrument { private volatile Thread systemThread; private volatile boolean cancelled; private final BlockingQueue<Runnable> tasks = new LinkedBlockingQueue<>(); @Override protected void onCreate(Env env) { // Create and start a Thread for the asynchronous task. // Remember the Thread reference to stop and join it in // the finalizeContext systemThread = env.createSystemThread(() -> { while (!cancelled) { try { Runnable task = tasks.poll(Integer.MAX_VALUE, SECONDS); if (task != null) { task.run(); } } catch (InterruptedException ie) { // pass to cancelled check } } }); systemThread.start(); } @Override protected void onDispose(Env env) { // Stop and join system thread. cancelled = true; systemThread.interrupt(); boolean interrupted = false; boolean terminated = false; while (!terminated) { try { systemThread.join(); terminated = true; } catch (InterruptedException ie) { interrupted = true; } } if (interrupted) { Thread.currentThread().interrupt(); } } }
- Parameters:
runnable
- the runnable to run on this thread.threadGroup
- the thread group, passed on to the underlyingThread
.- Throws:
IllegalStateException
- if the engine is already closed.- Since:
- 22.3
- See Also:
-
getSandboxPolicy
Returns the engine'sSandboxPolicy
. An instrument can use the returned sandbox policy to make instrument-specific verifications that the sandbox requirements are met. These verifications should be made as early as possible in theTruffleInstrument.onCreate(Env)
method.- Since:
- 23.0
- See Also:
-