1 /*
 2  * Copyright (c) 2020, Oracle and/or its affiliates. All rights reserved.
 3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 4  *
 5  * This code is free software; you can redistribute it and/or modify it
 6  * under the terms of the GNU General Public License version 2 only, as
 7  * published by the Free Software Foundation.  Oracle designates this
 8  * particular file as subject to the "Classpath" exception as provided
 9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 
26 package java.lang;
27 
28 /**
29  * A primitive class implements the {@code NonTearable} interface to
30  * request that the JVM take extra care to avoid structure tearing
31  * when loading or storing any value of the class to a field or array
32  * element.  Normally, only fields declared {@code volatile} are
33  * protected against structure tearing, but a class that implements
34  * this marker interface will never have its values torn, even when
35  * they are stored in array elements or in non-{@code volatile}
36  * fields, and even when multiple threads perform racing writes.
37  *
38  * <p> An primitive instance of multiple components is said to be "torn"
39  * when two racing threads compete to write those components, and one
40  * thread writes some components while another thread writes other
41  * components, so a subsequent observer will read a hybrid composed,
42  * as if "out of thin air", of field values from both racing writes.
43  * Tearing can also occur when the effects of two non-racing writes
44  * are observed by a racing read.  In general, structure tearing
45  * requires a read and two writes (initialization counting as a write)
46  * of a multi-component value, with a race between any two of the
47  * accesses.  The effect can also be described as if the Java memory
48  * model break up primitive classinstance reads and writes into reads and
49  * writes of their various fields, as it does with longs and doubles
50  * (JLS 17.7).
51  *
52  * <p> In extreme cases, the hybrid observed after structure tearing
53  * might be a value which is impossible to construct by normal means.
54  * If data integrity or security depends on proper construction,
55  * the class should be declared as implementing {@code NonTearable}.
56  *
57  * @author  John Rose
58  * @since   (valhalla)
59  */
60 public interface NonTearable {
61     // TO DO: Finalize name.
62     // TO DO: Decide whether and how to restrict this type to
63     // primitive classes only, or if not, whether to document its
64     // non-effect on identity classes.
65 }