| /* |
| * Written by Doug Lea with assistance from members of JCP JSR-166 |
| * Expert Group and released to the public domain, as explained at |
| * http://creativecommons.org/publicdomain/zero/1.0/ |
| */ |
| |
| package java.util.concurrent.atomic; |
| |
| /** |
| * A set of methods providing fine-grained control over happens-before |
| * and synchronization order relations among reads and/or writes. The |
| * methods of this class are designed for use in uncommon situations |
| * where declaring variables {@code volatile} or {@code final}, using |
| * instances of atomic classes, using {@code synchronized} blocks or |
| * methods, or using other synchronization facilities are not possible |
| * or do not provide the desired control. |
| * |
| * <p><b>Memory Ordering.</b> There are three methods for controlling |
| * ordering relations among memory accesses (i.e., reads and |
| * writes). Method {@code orderWrites} is typically used to enforce |
| * order between two writes, and {@code orderAccesses} between a write |
| * and a read. Method {@code orderReads} is used to enforce order |
| * between two reads with respect to other {@code orderWrites} and/or |
| * {@code orderAccesses} invocations. The formally specified |
| * properties of these methods described below provide |
| * platform-independent guarantees that are honored by all levels of a |
| * platform (compilers, systems, processors). The use of these |
| * methods may result in the suppression of otherwise valid compiler |
| * transformations and optimizations that could visibly violate the |
| * specified orderings, and may or may not entail the use of |
| * processor-level "memory barrier" instructions. |
| * |
| * <p>Each ordering method accepts a {@code ref} argument, and |
| * controls ordering among accesses with respect to this reference. |
| * Invocations must be placed <em>between</em> accesses performed in |
| * expression evaluations and assignment statements to control the |
| * orderings of prior versus subsequent accesses appearing in program |
| * order. These methods also return their arguments to simplify |
| * correct usage in these contexts. |
| * |
| * <p>Usages of ordering methods almost always take one of the forms |
| * illustrated in the examples below. These idioms arrange some of |
| * the ordering properties associated with {@code volatile} and |
| * related language-based constructions, but without other |
| * compile-time and runtime benefits that make language-based |
| * constructions far better choices when they are applicable. Usages |
| * should be restricted to the control of strictly internal |
| * implementation matters inside a class or package, and must either |
| * avoid or document any consequent violations of ordering or safety |
| * properties expected by users of a class employing them. |
| * |
| * <p><b>Reachability.</b> Method {@code reachabilityFence} |
| * establishes an ordering for strong reachability (as defined in the |
| * {@link java.lang.ref} package specification) with respect to |
| * garbage collection. Method {@code reachabilityFence} differs from |
| * the others in that it controls relations that are otherwise only |
| * implicit in a program -- the reachability conditions triggering |
| * garbage collection. As illustrated in the sample usages below, |
| * this method is applicable only when reclamation may have visible |
| * effects, which is possible for objects with finalizers (see Section |
| * 12.6 of the Java Language Specification) that are implemented in |
| * ways that rely on ordering control for correctness. |
| * |
| * <p><b>Sample Usages</b> |
| * |
| * <p><b>Safe publication.</b> With care, method {@code orderWrites} |
| * may be used to obtain the memory safety effects of {@code final} |
| * for a field that cannot be declared as {@code final}, because its |
| * primary initialization cannot be performed in a constructor, in |
| * turn because it is used in a framework requiring that all classes |
| * have a no-argument constructor; as in: |
| * |
| * <pre> {@code |
| * class WidgetHolder { |
| * private Widget widget; |
| * public WidgetHolder() {} |
| * public static WidgetHolder newWidgetHolder(Params params) { |
| * WidgetHolder h = new WidgetHolder(); |
| * h.widget = new Widget(params); |
| * return Fences.orderWrites(h); |
| * } |
| * }}</pre> |
| * |
| * Here, the invocation of {@code orderWrites} ensures that the |
| * effects of the widget assignment are ordered before those of any |
| * (unknown) subsequent stores of {@code h} in other variables that |
| * make {@code h} available for use by other objects. Initialization |
| * sequences using {@code orderWrites} require more care than those |
| * involving {@code final} fields. When {@code final} is not used, |
| * compilers cannot help you to ensure that the field is set correctly |
| * across all usages. You must fully initialize objects |
| * <em>before</em> the {@code orderWrites} invocation that makes |
| * references to them safe to assign to accessible variables. Further, |
| * initialization sequences must not internally "leak" the reference |
| * by using it as an argument to a callback method or adding it to a |
| * static data structure. If less constrained usages were required, |
| * it may be possible to cope using more extensive sets of fences, or |
| * as a normally better choice, using synchronization (locking). |
| * Conversely, if it were possible to do so, the best option would be |
| * to rewrite class {@code WidgetHolder} to use {@code final}. |
| * |
| * <p>An alternative approach is to place similar mechanics in the |
| * (sole) method that makes such objects available for use by others. |
| * Here is a stripped-down example illustrating the essentials. In |
| * practice, among other changes, you would use access methods instead |
| * of a public field. |
| * |
| * <pre> {@code |
| * class AnotherWidgetHolder { |
| * public Widget widget; |
| * void publish(Widget w) { |
| * this.widget = Fences.orderWrites(w); |
| * } |
| * // ... |
| * }}</pre> |
| * |
| * In this case, the {@code orderWrites} invocation occurs before the |
| * store making the object available. Correctness again relies on |
| * ensuring that there are no leaks prior to invoking this method, and |
| * that it really is the <em>only</em> means of accessing the |
| * published object. This approach is not often applicable -- |
| * normally you would publish objects using a thread-safe collection |
| * that itself guarantees the expected ordering relations. However, it |
| * may come into play in the construction of such classes themselves. |
| * |
| * <p><b>Safely updating fields.</b> Outside of the initialization |
| * idioms illustrated above, Fence methods ordering writes must be |
| * paired with those ordering reads. To illustrate, suppose class |
| * {@code c} contains an accessible variable {@code data} that should |
| * have been declared as {@code volatile} but wasn't: |
| * |
| * <pre> {@code |
| * class C { |
| * Object data; // need volatile access but not volatile |
| * // ... |
| * } |
| * |
| * class App { |
| * Object getData(C c) { |
| * return Fences.orderReads(c).data; |
| * } |
| * |
| * void setData(C c) { |
| * Object newValue = ...; |
| * c.data = Fences.orderWrites(newValue); |
| * Fences.orderAccesses(c); |
| * } |
| * // ... |
| * }}</pre> |
| * |
| * Method {@code getData} provides an emulation of {@code volatile} |
| * reads of (non-long/double) fields by ensuring that the read of |
| * {@code c} obtained as an argument is ordered before subsequent |
| * reads using this reference, and then performs the read of its |
| * field. Method {@code setData} provides an emulation of volatile |
| * writes, ensuring that all other relevant writes have completed, |
| * then performing the assignment, and then ensuring that the write is |
| * ordered before any other access. These techniques may apply even |
| * when fields are not directly accessible, in which case calls to |
| * fence methods would surround calls to methods such as {@code |
| * c.getData()}. However, these techniques cannot be applied to |
| * {@code long} or {@code double} fields because reads and writes of |
| * fields of these types are not guaranteed to be |
| * atomic. Additionally, correctness may require that all accesses of |
| * such data use these kinds of wrapper methods, which you would need |
| * to manually ensure. |
| * |
| * <p>More generally, Fence methods can be used in this way to achieve |
| * the safety properties of {@code volatile}. However their use does |
| * not necessarily guarantee the full sequential consistency |
| * properties specified in the Java Language Specification chapter 17 |
| * for programs using {@code volatile}. In particular, emulation using |
| * Fence methods is not guaranteed to maintain the property that |
| * {@code volatile} operations performed by different threads are |
| * observed in the same order by all observer threads. |
| * |
| * <p><b>Acquire/Release management of threadsafe objects</b>. It may |
| * be possible to use weaker conventions for volatile-like variables |
| * when they are used to keep track of objects that fully manage their |
| * own thread-safety and synchronization. Here, an acquiring read |
| * operation remains the same as a volatile-read, but a releasing |
| * write differs by virtue of not itself ensuring an ordering of its |
| * write with subsequent reads, because the required effects are |
| * already ensured by the referenced objects. |
| * For example: |
| * |
| * <pre> {@code |
| * class Item { |
| * synchronized f(); // ALL methods are synchronized |
| * // ... |
| * } |
| * |
| * class ItemHolder { |
| * private Item item; |
| * Item acquireItem() { |
| * return Fences.orderReads(item); |
| * } |
| * |
| * void releaseItem(Item x) { |
| * item = Fences.orderWrites(x); |
| * } |
| * |
| * // ... |
| * }}</pre> |
| * |
| * Because this construction avoids use of {@code orderAccesses}, |
| * which is typically more costly than the other fence methods, it may |
| * result in better performance than using {@code volatile} or its |
| * emulation. However, as is the case with most applications of fence |
| * methods, correctness relies on the usage context -- here, the |
| * thread safety of {@code Item}, as well as the lack of need for full |
| * volatile semantics inside this class itself. However, the second |
| * concern means that it can be difficult to extend the {@code |
| * ItemHolder} class in this example to be more useful. |
| * |
| * <p><b>Avoiding premature finalization.</b> Finalization may occur |
| * whenever a Java Virtual Machine detects that no reference to an |
| * object will ever be stored in the heap: A garbage collector may |
| * reclaim an object even if the fields of that object are still in |
| * use, so long as the object has otherwise become unreachable. This |
| * may have surprising and undesirable effects in cases such as the |
| * following example in which the bookkeeping associated with a class |
| * is managed through array indices. Here, method {@code action} |
| * uses a {@code reachabilityFence} to ensure that the Resource |
| * object is not reclaimed before bookkeeping on an associated |
| * ExternalResource has been performed; in particular here, to ensure |
| * that the array slot holding the ExternalResource is not nulled out |
| * in method {@link Object#finalize}, which may otherwise run |
| * concurrently. |
| * |
| * <pre> {@code |
| * class Resource { |
| * private static ExternalResource[] externalResourceArray = ... |
| * |
| * int myIndex; |
| * Resource(...) { |
| * myIndex = ... |
| * externalResourceArray[myIndex] = ...; |
| * ... |
| * } |
| * protected void finalize() { |
| * externalResourceArray[myIndex] = null; |
| * ... |
| * } |
| * public void action() { |
| * try { |
| * // ... |
| * int i = myIndex; |
| * Resource.update(externalResourceArray[i]); |
| * } finally { |
| * Fences.reachabilityFence(this); |
| * } |
| * } |
| * private static void update(ExternalResource ext) { |
| * ext.status = ...; |
| * } |
| * }}</pre> |
| * |
| * Here, the call to {@code reachabilityFence} is nonintuitively |
| * placed <em>after</em> the call to {@code update}, to ensure that |
| * the array slot is not nulled out by {@link Object#finalize} before |
| * the update, even if the call to {@code action} was the last use of |
| * this object. This might be the case if for example a usage in a |
| * user program had the form {@code new Resource().action();} which |
| * retains no other reference to this Resource. While probably |
| * overkill here, {@code reachabilityFence} is placed in a {@code |
| * finally} block to ensure that it is invoked across all paths in the |
| * method. In a method with more complex control paths, you might |
| * need further precautions to ensure that {@code reachabilityFence} |
| * is encountered along all of them. |
| * |
| * <p>It is sometimes possible to better encapsulate use of |
| * {@code reachabilityFence}. Continuing the above example, if it |
| * were OK for the call to method update to proceed even if the |
| * finalizer had already executed (nulling out slot), then you could |
| * localize use of {@code reachabilityFence}: |
| * |
| * <pre> {@code |
| * public void action2() { |
| * // ... |
| * Resource.update(getExternalResource()); |
| * } |
| * private ExternalResource getExternalResource() { |
| * ExternalResource ext = externalResourceArray[myIndex]; |
| * Fences.reachabilityFence(this); |
| * return ext; |
| * }}</pre> |
| * |
| * <p>Method {@code reachabilityFence} is not required in |
| * constructions that themselves ensure reachability. For example, |
| * because objects that are locked cannot in general be reclaimed, it |
| * would suffice if all accesses of the object, in all methods of |
| * class Resource (including {@code finalize}) were enclosed in {@code |
| * synchronized (this)} blocks. (Further, such blocks must not include |
| * infinite loops, or themselves be unreachable, which fall into the |
| * corner case exceptions to the "in general" disclaimer.) However, |
| * method {@code reachabilityFence} remains a better option in cases |
| * where this approach is not as efficient, desirable, or possible; |
| * for example because it would encounter deadlock. |
| * |
| * <p><b>Formal Properties.</b> |
| * |
| * <p>Using the terminology of The Java Language Specification chapter |
| * 17, the rules governing the semantics of the methods of this class |
| * are as follows: |
| * |
| * <p> The following is still under construction. |
| * |
| * <dl> |
| * |
| * <dt><b>[Definitions]</b> |
| * <dd> |
| * <ul> |
| * |
| * <li>Define <em>sequenced(a, b)</em> to be true if <em>a</em> |
| * occurs before <em>b</em> in <em>program order</em>. |
| * |
| * <li>Define <em>accesses(a, p)</em> to be true if |
| * <em>a</em> is a read or write of a field (or if an array, an |
| * element) of the object referenced by <em>p</em>. |
| * |
| * <li>Define <em>deeplyAccesses(a, p)</em> to be true if either |
| * <em>accesses(a, p)</em> or <em>deeplyAccesses(a, q)</em> where |
| * <em>q</em> is the value seen by some read <em>r</em> |
| * such that <em>accesses(r, p)</em>. |
| * |
| * </ul> |
| * <p> |
| * <dt><b>[Matching]</b> |
| * <dd> Given: |
| * |
| * <ul> |
| * |
| * <li><em>p</em>, a reference to an object |
| * |
| * <li><em>wf</em>, an invocation of {@code orderWrites(p)} or |
| * {@code orderAccesses(p)} |
| * |
| * <li><em>w</em>, a write of value <em>p</em> |
| * |
| * <li> <em>rf</em>, an invocation of {@code orderReads(p)} or |
| * {@code orderAccesses(p)} |
| * |
| * <li> <em>r</em>, a read returning value <em>p</em> |
| * |
| * </ul> |
| * If: |
| * <ul> |
| * <li>sequenced(wf, w) |
| * <li>read <em>r</em> sees write <em>w</em> |
| * <li>sequenced(r, rf) |
| * </ul> |
| * Then: |
| * <ul> |
| * |
| * <li> <em>wf happens-before rf</em> |
| * |
| * <li> <em>wf</em> precedes <em>rf</em> in the |
| * <em>synchronization order</em> |
| * |
| * <li> If (<em>r1</em>, <em>w1</em>) and (<em>r2</em>, |
| * <em>w2</em>) are two pairs of reads and writes, both |
| * respectively satisfying the above conditions for <em>p</em>, |
| * and sequenced(r1, r2) then it is not the case that <em>w2 |
| * happens-before w1</em>. |
| * |
| * </ul> |
| * <p> |
| * <dt><b>[Initial Reads]</b> |
| * <dd> Given: |
| * |
| * <ul> |
| * |
| * <li><em>p</em>, a reference to an object |
| * |
| * <li> <em>a</em>, an access where deeplyAccesses(a, p) |
| * |
| * <li><em>wf</em>, an invocation of {@code orderWrites(p)} or |
| * {@code orderAccesses(p)} |
| * |
| * <li><em>w</em>, a write of value <em>p</em> |
| * |
| * <li> <em>r</em>, a read returning value <em>p</em> |
| * |
| * <li> <em>b</em>, an access where accesses(b, p) |
| * |
| * </ul> |
| * If: |
| * <ul> |
| * <li>sequenced(a, wf); |
| * <li>sequenced(wf, w) |
| * <li>read <em>r</em> sees write <em>w</em>, and |
| * <em>r</em> is the first read by some thread |
| * <em>t</em> that sees value <em>p</em> |
| * <li>sequenced(r, b) |
| * </ul> |
| * Then: |
| * <ul> |
| * <li> the effects of <em>b</em> are constrained |
| * by the relation <em>a happens-before b</em>. |
| * </ul> |
| * <p> |
| * <dt><b>[orderAccesses]</b> |
| * <dd> Given: |
| * |
| * <ul> |
| * <li><em>p</em>, a reference to an object |
| * <li><em>f</em>, an invocation of {@code orderAccesses(p)} |
| * </ul> |
| * If: |
| * <ul> |
| * <li>sequenced(f, w) |
| * </ul> |
| * |
| * Then: |
| * |
| * <ul> |
| * |
| * <li> <em>f</em> is an element of the <em>synchronization order</em>. |
| * |
| * </ul> |
| * <p> |
| * <dt><b>[Reachability]</b> |
| * <dd> Given: |
| * |
| * <ul> |
| * |
| * <li><em>p</em>, a reference to an object |
| * |
| * <li><em>f</em>, an invocation of {@code reachabilityFence(p)} |
| * |
| * <li><em>a</em>, an access where accesses(a, p) |
| * |
| * <li><em>b</em>, an action (by a garbage collector) taking |
| * the form of an invocation of {@code |
| * p.finalize()} or of enqueing any {@link |
| * java.lang.ref.Reference} constructed with argument <em>p</em> |
| * |
| * </ul> |
| * |
| * If: |
| * <ul> |
| * <li>sequenced(a, f) |
| * </ul> |
| * |
| * Then: |
| * |
| * <ul> |
| * |
| * <li> <em>a happens-before b</em>. |
| * |
| * </ul> |
| * |
| * </dl> |
| * |
| * @since 1.7 |
| * @hide |
| * @author Doug Lea |
| */ |
| public class Fences { |
| private Fences() {} // Non-instantiable |
| |
| /* |
| * The methods of this class are intended to be intrinisified by a |
| * JVM. However, we provide correct but inefficient Java-level |
| * code that simply reads and writes a static volatile |
| * variable. Without JVM support, the consistency effects are |
| * stronger than necessary, and the memory contention effects can |
| * be a serious performance issue. |
| */ |
| private static volatile int theVolatile; |
| |
| /** |
| * Informally: Ensures that a read of the given reference prior to |
| * the invocation of this method occurs before a subsequent use of |
| * the given reference with the effect of reading or writing a |
| * field (or if an array, element) of the referenced object. The |
| * use of this method is sensible only when paired with other |
| * invocations of {@link #orderWrites} and/or {@link |
| * #orderAccesses} for the given reference. For details, see the |
| * class documentation for this class. |
| * |
| * @param ref the reference. If null, this method has no effect. |
| * @return the given ref, to simplify usage |
| */ |
| public static <T> T orderReads(T ref) { |
| int ignore = theVolatile; |
| return ref; |
| } |
| |
| /** |
| * Informally: Ensures that a use of the given reference with the |
| * effect of reading or writing a field (or if an array, element) |
| * of the referenced object, prior to the invocation of this |
| * method occur before a subsequent write of the reference. For |
| * details, see the class documentation for this class. |
| * |
| * @param ref the reference. If null, this method has no effect. |
| * @return the given ref, to simplify usage |
| */ |
| public static <T> T orderWrites(T ref) { |
| theVolatile = 0; |
| return ref; |
| } |
| |
| /** |
| * Informally: Ensures that accesses (reads or writes) using the |
| * given reference prior to the invocation of this method occur |
| * before subsequent accesses. For details, see the class |
| * documentation for this class. |
| * |
| * @param ref the reference. If null, this method has no effect. |
| * @return the given ref, to simplify usage |
| */ |
| public static <T> T orderAccesses(T ref) { |
| theVolatile = 0; |
| return ref; |
| } |
| |
| /** |
| * Ensures that the object referenced by the given reference |
| * remains <em>strongly reachable</em> (as defined in the {@link |
| * java.lang.ref} package documentation), regardless of any prior |
| * actions of the program that might otherwise cause the object to |
| * become unreachable; thus, the referenced object is not |
| * reclaimable by garbage collection at least until after the |
| * invocation of this method. Invocation of this method does not |
| * itself initiate garbage collection or finalization. |
| * |
| * <p>See the class-level documentation for further explanation |
| * and usage examples. |
| * |
| * @param ref the reference. If null, this method has no effect. |
| */ |
| public static void reachabilityFence(Object ref) { |
| if (ref != null) { |
| synchronized (ref) {} |
| } |
| } |
| } |