com.oracle.truffle.api.vm

Class PolyglotRuntime.Instrument

java.lang.Object

com.oracle.truffle.api.vm.PolyglotRuntime.Instrument

Enclosing class:

PolyglotRuntime

public class PolyglotRuntime.Instrument
extends Object

A handle for an instrument installed in the runtime, usable from other threads, that can observe and inject behavior into language execution. The handle provides access to the instrument's metadata and allows the instrument to be dynamically enabled/disabled in the runtime.

All methods here, as well as instrumentation services in general, can be used safely from threads other than the engine's single execution thread.

Refer to TruffleInstrument for information about implementing and installing instruments.

Since:

0.25

See Also:

PolyglotRuntime.getInstruments()

Method Summary

Modifier and Type	Method and Description
String	getId() Gets the id clients can use to acquire this instrument.
String	getName() Gets a human readable name of this instrument.
String	getVersion() Gets the version of this instrument.
boolean	isEnabled() Returns whether this instrument is currently enabled in the engine.
<T> T	lookup(Class<T> type) Returns an additional service provided by this instrument, specified by type.
void	setEnabled(boolean enabled) Enables/disables this instrument in the engine.
String	toString()

Methods inherited from class java.lang.Object

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

Method Detail

getId

public String getId()

Gets the id clients can use to acquire this instrument.

Returns:

this instrument's unique id

Since:

0.9

getName

public String getName()

Gets a human readable name of this instrument.

Returns:

this instrument's user-friendly name

Since:

0.9

getVersion

public String getVersion()

Gets the version of this instrument.

Returns:

this instrument's version

Since:

0.9

isEnabled

public boolean isEnabled()

Returns whether this instrument is currently enabled in the engine.

Returns:

this instrument's status in the engine

Since:

0.9

lookup

public <T> T lookup(Class<T> type)

Returns an additional service provided by this instrument, specified by type.

Here is an example for locating a hypothetical DebuggerController:

PolyglotRuntime runtime = engine.getRuntime();
PolyglotRuntime.Instrument instrument = runtime.getInstruments().get(DebuggerExample.ID);
assert !instrument.isEnabled() : "Not enabled yet";
debugger = instrument.lookup(DebuggerController.class);
assert instrument.isEnabled() : "Got enabled";
assert debugger != null : "We can control the debugger";

Type Parameters:

T - the type of the service

Parameters:

type - class of the service that is being requested

Returns:

instance of requested type, null if no such service is available

Since:

0.9

setEnabled

public void setEnabled(boolean enabled)

Enables/disables this instrument in the engine.

Parameters:

enabled - true to enable false to disable

Since:

0.9

toString

public String toString()

Overrides:

toString in class Object

Since:

0.9