jdk.internal.vm.annotation

Annotation Type Stable

@Target(value=FIELD)
 @Retention(value=RUNTIME)
public @interface Stable

A field may be annotated as stable if all of its component variables changes value at most once. A field's value counts as its component value. If the field is typed as an array, then all the non-null components of the array, of depth up to the rank of the field's array type, also count as component values. By extension, any variable (either array or field) which has annotated as stable is called a stable variable, and its non-null or non-zero value is called a stable value.

Since all fields begin with a default value of null for references (resp., zero for primitives), it follows that this annotation indicates that the first non-null (resp., non-zero) value stored in the field will never be changed.

If the field is not of an array type, there are no array elements, then the value indicated as stable is simply the value of the field. If the dynamic type of the field value is an array but the static type is not, the components of the array are not regarded as stable.

If the field is an array type, then both the field value and all the components of the field value (if the field value is non-null) are indicated to be stable. If the field type is an array type with rank N > 1, then each component of the field value (if the field value is non-null), is regarded as a stable array of rank N-1.

Fields which are declared final may also be annotated as stable. Since final fields already behave as stable values, such an annotation conveys no additional information regarding change of the field's value, but still conveys information regarding change of additional components values if the type of the field is an array type (as described above).

The HotSpot VM relies on this annotation to promote a non-null (resp., non-zero) component value to a constant, thereby enabling superior optimizations of code depending on such a value (such as constant folding). More specifically, the HotSpot VM will process non-null stable fields (final or otherwise) in a similar manner to static final fields with respect to promoting the field's value to a constant. Thus, placing aside the differences for null/non-null values and arrays, a final stable field is treated as if it is really final from both the Java language and the HotSpot VM.

It is (currently) undefined what happens if a field annotated as stable is given a third value (by explicitly updating a stable field, a component of a stable array, or a final stable field via reflection or other means). Since the HotSpot VM promotes a non-null component value to constant, it may be that the Java memory model would appear to be broken, if such a constant (the second value of the field) is used as the value of the field even after the field value has changed (to a third value).