jaroslav@1646: /*
jaroslav@1646:  * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
jaroslav@1646:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
jaroslav@1646:  *
jaroslav@1646:  * This code is free software; you can redistribute it and/or modify it
jaroslav@1646:  * under the terms of the GNU General Public License version 2 only, as
jaroslav@1646:  * published by the Free Software Foundation.  Oracle designates this
jaroslav@1646:  * particular file as subject to the "Classpath" exception as provided
jaroslav@1646:  * by Oracle in the LICENSE file that accompanied this code.
jaroslav@1646:  *
jaroslav@1646:  * This code is distributed in the hope that it will be useful, but WITHOUT
jaroslav@1646:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
jaroslav@1646:  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
jaroslav@1646:  * version 2 for more details (a copy is included in the LICENSE file that
jaroslav@1646:  * accompanied this code).
jaroslav@1646:  *
jaroslav@1646:  * You should have received a copy of the GNU General Public License version
jaroslav@1646:  * 2 along with this work; if not, write to the Free Software Foundation,
jaroslav@1646:  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
jaroslav@1646:  *
jaroslav@1646:  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
jaroslav@1646:  * or visit www.oracle.com if you need additional information or have any
jaroslav@1646:  * questions.
jaroslav@1646:  */
jaroslav@1646: 
jaroslav@1646: package java.lang.invoke;
jaroslav@1646: 
jaroslav@1646: import java.lang.annotation.*;
jaroslav@1646: 
jaroslav@1646: /**
jaroslav@1646:  * A field may be annotated as stable if all of its component variables
jaroslav@1646:  * changes value at most once.
jaroslav@1646:  * A field's value counts as its component value.
jaroslav@1646:  * If the field is typed as an array, then all the non-null components
jaroslav@1646:  * of the array, of depth up to the rank of the field's array type,
jaroslav@1646:  * also count as component values.
jaroslav@1646:  * By extension, any variable (either array or field) which has annotated
jaroslav@1646:  * as stable is called a stable variable, and its non-null or non-zero
jaroslav@1646:  * value is called a stable value.
jaroslav@1646:  * <p>
jaroslav@1646:  * Since all fields begin with a default value of null for references
jaroslav@1646:  * (resp., zero for primitives), it follows that this annotation indicates
jaroslav@1646:  * that the first non-null (resp., non-zero) value stored in the field
jaroslav@1646:  * will never be changed.
jaroslav@1646:  * <p>
jaroslav@1646:  * If the field is not of an array type, there are no array elements,
jaroslav@1646:  * then the value indicated as stable is simply the value of the field.
jaroslav@1646:  * If the dynamic type of the field value is an array but the static type
jaroslav@1646:  * is not, the components of the array are <em>not</em> regarded as stable.
jaroslav@1646:  * <p>
jaroslav@1646:  * If the field is an array type, then both the field value and
jaroslav@1646:  * all the components of the field value (if the field value is non-null)
jaroslav@1646:  * are indicated to be stable.
jaroslav@1646:  * If the field type is an array type with rank {@code N &gt; 1},
jaroslav@1646:  * then each component of the field value (if the field value is non-null),
jaroslav@1646:  * is regarded as a stable array of rank {@code N-1}.
jaroslav@1646:  * <p>
jaroslav@1646:  * Fields which are declared {@code final} may also be annotated as stable.
jaroslav@1646:  * Since final fields already behave as stable values, such an annotation
jaroslav@1646:  * indicates no additional information, unless the type of the field is
jaroslav@1646:  * an array type.
jaroslav@1646:  * <p>
jaroslav@1646:  * It is (currently) undefined what happens if a field annotated as stable
jaroslav@1646:  * is given a third value.  In practice, if the JVM relies on this annotation
jaroslav@1646:  * to promote a field reference to a constant, it may be that the Java memory
jaroslav@1646:  * model would appear to be broken, if such a constant (the second value of the field)
jaroslav@1646:  * is used as the value of the field even after the field value has changed.
jaroslav@1646:  */
jaroslav@1646: /* package-private */
jaroslav@1646: @Target(ElementType.FIELD)
jaroslav@1646: @Retention(RetentionPolicy.RUNTIME)
jaroslav@1646: @interface Stable {
jaroslav@1646: }