Package com.oracle.truffle.api.bytecode

Annotation Interface Instrumentation

@Retention(SOURCE)
@Target(TYPE)
public @interface Instrumentation

Instrumentations are operations that can be dynamically enabled at runtime. Dynamically enabling them at runtime enables to use them to implement features that are not commonly enabled, like tracing, language internal debugging, profiling or taint tracking.

Instrumentations are emitted like regular operations with the builder, but only generate instructions if they are enabled in the BytecodeConfig. A bytecode config with enabled instrumentations can be provided at parse time, when deserializing or using the update method at any time.

Unlike regular operations, instrumentations must have transparent stack effects. This is important to ensure that that the stack layout remains compatible when instrumentations are enabled at runtime. This means that instrumentations can either have no dynamic operands and no return value or one dynamic operand and one return value. Note that instrumentations can declare constant operands since those do not affect the stack.

Instrumentations with one operand and return value may freely modify values observed at runtime. Boxing elimination is reset when new instrumentations are enabled, but will also work for instrumentation operations.

Note that instrumentations cannot specify any tags, because tags must be stable and cannot be enabled at runtime. Instrumentations can also not be used as boolean converters for short circuits.

Since:

24.2

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	javadoc	Optional documentation for the instrumentation.

Element Details

javadoc

String javadoc

Optional documentation for the instrumentation. This documentation is included in the javadoc for the generated interpreter.

Since:

24.2

Default:

""