Class ConstantOptionKey<T>

java.lang.Object
org.graalvm.options.OptionKey<T>
org.graalvm.options.ConstantOptionKey<T>
public final class ConstantOptionKey<T> extends OptionKey<T>
Represents an OptionKey whose value is fixed before the polyglot runtime is initialized and cannot be changed afterwards. Because the value is immutable after initialization, getConstantValue() is eligible for constant folding by the compiler, allowing branches guarded by this option to be eliminated from compiled code.

The option value is initialized from the system property -Dpolyglot.<option-name>=<value>, which must be set before the polyglot runtime is initialized (i.e. before the containing class is loaded). If the system property is absent, the default value is used. On HotSpot, this means the property must be present on the JVM command line. In a GraalVM native image, the property is read during image building, so the value is baked into the image.

Once the value has been set, getConstantValue() returns the same value for the lifetime of the runtime. The GraalVM compiler constant-folds calls to this method when the receiver is a known heap constant (e.g. a static final field), enabling dead-branch elimination.

Since:
25.1

  • Constructor Details

    • ConstantOptionKey

      public ConstantOptionKey(T defaultValue)
      Constructs a new constant option key with the given default value. The default value is used when no value is specified via the system property -Dpolyglot.<option-name>. Throws IllegalArgumentException if no default OptionType could be resolved for the given type. The default value must not be null.
      Since:
      25.1

    • ConstantOptionKey

      public ConstantOptionKey(T defaultValue, OptionType<T> type)
      Constructs a new constant option key with an explicit option type and default value. The default value is used when no value is specified via the system property -Dpolyglot.<option-name>.
      Since:
      25.1

  • Method Details

    • getConstantValue

      public T getConstantValue()
      Returns the constant value of this option key. The value is fixed at class initialization time and remains immutable for the lifetime of the runtime, making this method eligible for constant folding by the GraalVM compiler when the receiver is a heap constant.
      Throws:
      IllegalStateException - if the value has not been set yet, which should not happen in normal usage as the generated option descriptors static initializer sets the value at class load time.
      Since:
      25.1

    • setConstantValue

      public void setConstantValue(T value)
      Sets the constant value of this option key. This method is intended to be called from the generated option descriptors static initializer and must not be called after the polyglot runtime has started. In a native image, it must not be called at image run time.
      Throws:
      IllegalStateException - if the value has already been set, or if called at native image run time.
      Since:
      25.1