63 * waiting for non-exclusive access, returning a stamp that can be |
63 * waiting for non-exclusive access, returning a stamp that can be |
64 * used in method {@link #unlockRead} to release the lock. Untimed |
64 * used in method {@link #unlockRead} to release the lock. Untimed |
65 * and timed versions of {@code tryReadLock} are also provided. |
65 * and timed versions of {@code tryReadLock} are also provided. |
66 * |
66 * |
67 * <li><b>Optimistic Reading.</b> Method {@link #tryOptimisticRead} |
67 * <li><b>Optimistic Reading.</b> Method {@link #tryOptimisticRead} |
68 * returns a non-zero stamp only if the lock is not currently held |
68 * returns a non-zero stamp only if the lock is not currently held in |
69 * in write mode. Method {@link #validate} returns true if the lock |
69 * write mode. Method {@link #validate} returns true if the lock has not |
70 * has not been acquired in write mode since obtaining a given |
70 * been acquired in write mode since obtaining a given stamp, in which |
71 * stamp. This mode can be thought of as an extremely weak version |
71 * case all actions prior to the most recent write lock release |
72 * of a read-lock, that can be broken by a writer at any time. The |
72 * happen-before actions following the call to {@code tryOptimisticRead}. |
73 * use of optimistic mode for short read-only code segments often |
73 * This mode can be thought of as an extremely weak version of a |
74 * reduces contention and improves throughput. However, its use is |
74 * read-lock, that can be broken by a writer at any time. The use of |
75 * inherently fragile. Optimistic read sections should only read |
75 * optimistic read mode for short read-only code segments often reduces |
76 * fields and hold them in local variables for later use after |
76 * contention and improves throughput. However, its use is inherently |
77 * validation. Fields read while in optimistic mode may be wildly |
77 * fragile. Optimistic read sections should only read fields and hold |
78 * inconsistent, so usage applies only when you are familiar enough |
78 * them in local variables for later use after validation. Fields read |
79 * with data representations to check consistency and/or repeatedly |
79 * while in optimistic read mode may be wildly inconsistent, so usage |
80 * invoke method {@code validate()}. For example, such steps are |
80 * applies only when you are familiar enough with data representations to |
81 * typically required when first reading an object or array |
81 * check consistency and/or repeatedly invoke method {@code validate()}. |
82 * reference, and then accessing one of its fields, elements or |
82 * For example, such steps are typically required when first reading an |
83 * methods. |
83 * object or array reference, and then accessing one of its fields, |
|
84 * elements or methods. |
84 * |
85 * |
85 * </ul> |
86 * </ul> |
86 * |
87 * |
87 * <p>This class also supports methods that conditionally provide |
88 * <p>This class also supports methods that conditionally provide |
88 * conversions across the three modes. For example, method {@link |
89 * conversions across the three modes. For example, method {@link |
89 * #tryConvertToWriteLock} attempts to "upgrade" a mode, returning |
90 * #tryConvertToWriteLock} attempts to "upgrade" a mode, returning |
90 * a valid write stamp if (1) already in writing mode (2) in reading |
91 * a valid write stamp if (1) already in writing mode (2) in reading |
91 * mode and there are no other readers or (3) in optimistic mode and |
92 * mode and there are no other readers or (3) in optimistic read mode |
92 * the lock is available. The forms of these methods are designed to |
93 * and the lock is available. The forms of these methods are designed to |
93 * help reduce some of the code bloat that otherwise occurs in |
94 * help reduce some of the code bloat that otherwise occurs in |
94 * retry-based designs. |
95 * retry-based designs. |
95 * |
96 * |
96 * <p>StampedLocks are designed for use as internal utilities in the |
97 * <p>StampedLocks are designed for use as internal utilities in the |
97 * development of thread-safe components. Their use relies on |
98 * development of thread-safe components. Their use relies on |
126 * modes, this class does not directly implement the {@link Lock} or |
127 * modes, this class does not directly implement the {@link Lock} or |
127 * {@link ReadWriteLock} interfaces. However, a StampedLock may be |
128 * {@link ReadWriteLock} interfaces. However, a StampedLock may be |
128 * viewed {@link #asReadLock()}, {@link #asWriteLock()}, or {@link |
129 * viewed {@link #asReadLock()}, {@link #asWriteLock()}, or {@link |
129 * #asReadWriteLock()} in applications requiring only the associated |
130 * #asReadWriteLock()} in applications requiring only the associated |
130 * set of functionality. |
131 * set of functionality. |
|
132 * |
|
133 * <p><b>Memory Synchronization.</b> Methods with the effect of |
|
134 * successfully locking in any mode have the same memory |
|
135 * synchronization effects as a <em>Lock</em> action described in |
|
136 * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-17.html#jls-17.4"> |
|
137 * Chapter 17 of <cite>The Java™ Language Specification</cite></a>. |
|
138 * Methods successfully unlocking in write mode have the same memory |
|
139 * synchronization effects as an <em>Unlock</em> action. In optimistic |
|
140 * read usages, actions prior to the most recent write mode unlock action |
|
141 * are guaranteed to happen-before those following a tryOptimisticRead |
|
142 * only if a later validate returns true; otherwise there is no guarantee |
|
143 * that the reads between tryOptimisticRead and validate obtain a |
|
144 * consistent snapshot. |
131 * |
145 * |
132 * <p><b>Sample Usage.</b> The following illustrates some usage idioms |
146 * <p><b>Sample Usage.</b> The following illustrates some usage idioms |
133 * in a class that maintains simple two-dimensional points. The sample |
147 * in a class that maintains simple two-dimensional points. The sample |
134 * code illustrates some try/catch conventions even though they are |
148 * code illustrates some try/catch conventions even though they are |
135 * not strictly needed here because no exceptions can occur in their |
149 * not strictly needed here because no exceptions can occur in their |