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 allows them to be used 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 it will also work for instrumentation operations.

Note that instrumentations cannot specify any tags, because tags must be stable and new tags cannot be specified 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
    boolean
    forceCached
    Whether executing this operation should force the uncached interpreter (if enabled) to transition to cached.
    String
    javadoc
    Optional documentation for the instrumentation.

  • Element Details

    • forceCached

      boolean forceCached
      Whether executing this operation should force the uncached interpreter (if enabled) to transition to cached.
      Since:
      24.2
      See Also:
      Default:
      false

    • javadoc

      String javadoc
      Optional documentation for the instrumentation. This documentation is included in the javadoc for the generated interpreter.
      Since:
      24.2
      Default:
      ""