--- jsr166/src/jsr166e/StampedLock.java 2013/01/24 21:35:03 1.31
+++ jsr166/src/jsr166e/StampedLock.java 2013/07/14 19:55:05 1.37
@@ -5,8 +5,6 @@
*/
package jsr166e;
-
-import java.util.concurrent.ThreadLocalRandom;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.locks.Lock;
import java.util.concurrent.locks.Condition;
@@ -40,19 +38,20 @@ import java.util.concurrent.locks.LockSu
*
Optimistic Reading. Method {@link #tryOptimisticRead}
* returns a non-zero stamp only if the lock is not currently held
* in write mode. Method {@link #validate} returns true if the lock
- * has not since been acquired in write mode. This mode can be
- * thought of as an extremely weak version of a read-lock, that can
- * be broken by a writer at any time. The use of optimistic mode
- * for short read-only code segments often reduces contention and
- * improves throughput. However, its use is inherently fragile.
- * Optimistic read sections should only read fields and hold them in
- * local variables for later use after validation. Fields read while
- * in optimistic mode may be wildly inconsistent, so usage applies
- * only when you are familiar enough with data representations to
- * check consistency and/or repeatedly invoke method {@code
- * validate()}. For example, such steps are typically required when
- * first reading an object or array reference, and then accessing
- * one of its fields, elements or methods.
+ * has not been acquired in write mode since obtaining a given
+ * stamp. This mode can be thought of as an extremely weak version
+ * of a read-lock, that can be broken by a writer at any time. The
+ * use of optimistic mode for short read-only code segments often
+ * reduces contention and improves throughput. However, its use is
+ * inherently fragile. Optimistic read sections should only read
+ * fields and hold them in local variables for later use after
+ * validation. Fields read while in optimistic mode may be wildly
+ * inconsistent, so usage applies only when you are familiar enough
+ * with data representations to check consistency and/or repeatedly
+ * invoke method {@code validate()}. For example, such steps are
+ * typically required when first reading an object or array
+ * reference, and then accessing one of its fields, elements or
+ * methods.
*
*
*
@@ -118,34 +117,17 @@ import java.util.concurrent.locks.LockSu
* }
* }
*
- * double distanceFromOriginV1() { // A read-only method
- * long stamp;
- * if ((stamp = sl.tryOptimisticRead()) != 0L) { // optimistic
- * double currentX = x;
- * double currentY = y;
- * if (sl.validate(stamp))
- * return Math.sqrt(currentX * currentX + currentY * currentY);
- * }
- * stamp = sl.readLock(); // fall back to read lock
- * try {
- * double currentX = x;
- * double currentY = y;
- * return Math.sqrt(currentX * currentX + currentY * currentY);
- * } finally {
- * sl.unlockRead(stamp);
- * }
- * }
- *
- * double distanceFromOriginV2() { // combines code paths
- * double currentX = 0.0, currentY = 0.0;
- * for (long stamp = sl.tryOptimisticRead(); ; stamp = sl.readLock()) {
- * try {
- * currentX = x;
- * currentY = y;
- * } finally {
- * if (sl.tryConvertToOptimisticRead(stamp) != 0L) // unlock or validate
- * break;
- * }
+ * double distanceFromOrigin() { // A read-only method
+ * long stamp = sl.tryOptimisticRead();
+ * double currentX = x, currentY = y;
+ * if (!sl.validate(stamp)) {
+ * stamp = sl.readLock();
+ * try {
+ * currentX = x;
+ * currentY = y;
+ * } finally {
+ * sl.unlockRead(stamp);
+ * }
* }
* return Math.sqrt(currentX * currentX + currentY * currentY);
* }
@@ -252,6 +234,7 @@ public class StampedLock implements java
* motivation to further spread out contended locations, but might
* be subject to future improvements.
*/
+
private static final long serialVersionUID = -6001602636862214147L;
/** Number of processors, for spin control */
@@ -356,6 +339,8 @@ public class StampedLock implements java
* Behavior under timeout and interruption matches that specified
* for method {@link Lock#tryLock(long,TimeUnit)}.
*
+ * @param time the maximum time to wait for the lock
+ * @param unit the time unit of the {@code time} argument
* @return a stamp that can be used to unlock or convert mode,
* or zero if the lock is not available
* @throws InterruptedException if the current thread is interrupted
@@ -435,6 +420,8 @@ public class StampedLock implements java
* Behavior under timeout and interruption matches that specified
* for method {@link Lock#tryLock(long,TimeUnit)}.
*
+ * @param time the maximum time to wait for the lock
+ * @param unit the time unit of the {@code time} argument
* @return a stamp that can be used to unlock or convert mode,
* or zero if the lock is not available
* @throws InterruptedException if the current thread is interrupted
@@ -442,11 +429,17 @@ public class StampedLock implements java
*/
public long tryReadLock(long time, TimeUnit unit)
throws InterruptedException {
- long next, deadline;
+ long s, m, next, deadline;
long nanos = unit.toNanos(time);
if (!Thread.interrupted()) {
- if ((next = tryReadLock()) != 0L)
- return next;
+ if ((m = (s = state) & ABITS) != WBIT) {
+ if (m < RFULL) {
+ if (U.compareAndSwapLong(this, STATE, s, next = s + RUNIT))
+ return next;
+ }
+ else if ((next = tryIncReaderOverflow(s)) != 0L)
+ return next;
+ }
if (nanos <= 0L)
return 0L;
if ((deadline = System.nanoTime() + nanos) == 0L)
@@ -490,9 +483,12 @@ public class StampedLock implements java
* Returns true if the lock has not been exclusively acquired
* since issuance of the given stamp. Always returns false if the
* stamp is zero. Always returns true if the stamp represents a
- * currently held lock.
+ * currently held lock. Invoking this method with a value not
+ * obtained from {@link #tryOptimisticRead} or a locking method
+ * for this lock has no defined effect or result.
*
- * @return true if the lock has not been exclusively acquired
+ * @param stamp a stamp
+ * @return {@code true} if the lock has not been exclusively acquired
* since issuance of the given stamp; else false
*/
public boolean validate(long stamp) {
@@ -705,7 +701,7 @@ public class StampedLock implements java
* stamp value. This method may be useful for recovery after
* errors.
*
- * @return true if the lock was held, else false
+ * @return {@code true} if the lock was held, else false
*/
public boolean tryUnlockWrite() {
long s; WNode h;
@@ -723,7 +719,7 @@ public class StampedLock implements java
* requiring a stamp value. This method may be useful for recovery
* after errors.
*
- * @return true if the read lock was held, else false
+ * @return {@code true} if the read lock was held, else false
*/
public boolean tryUnlockRead() {
long s, m; WNode h;
@@ -741,31 +737,67 @@ public class StampedLock implements java
return false;
}
+ // status monitoring methods
+
+ /**
+ * Returns combined state-held and overflow read count for given
+ * state s.
+ */
+ private int getReadLockCount(long s) {
+ long readers;
+ if ((readers = s & RBITS) >= RFULL)
+ readers = RFULL + readerOverflow;
+ return (int) readers;
+ }
+
/**
- * Returns true if the lock is currently held exclusively.
+ * Returns {@code true} if the lock is currently held exclusively.
*
- * @return true if the lock is currently held exclusively
+ * @return {@code true} if the lock is currently held exclusively
*/
public boolean isWriteLocked() {
return (state & WBIT) != 0L;
}
/**
- * Returns true if the lock is currently held non-exclusively.
+ * Returns {@code true} if the lock is currently held non-exclusively.
*
- * @return true if the lock is currently held non-exclusively
+ * @return {@code true} if the lock is currently held non-exclusively
*/
public boolean isReadLocked() {
return (state & RBITS) != 0L;
}
- private void readObject(java.io.ObjectInputStream s)
- throws java.io.IOException, ClassNotFoundException {
- s.defaultReadObject();
- state = ORIGIN; // reset to unlocked state
+ /**
+ * Queries the number of read locks held for this lock. This
+ * method is designed for use in monitoring system state, not for
+ * synchronization control.
+ * @return the number of read locks held
+ */
+ public int getReadLockCount() {
+ return getReadLockCount(state);
}
/**
+ * Returns a string identifying this lock, as well as its lock
+ * state. The state, in brackets, includes the String {@code
+ * "Unlocked"} or the String {@code "Write-locked"} or the String
+ * {@code "Read-locks:"} followed by the current number of
+ * read-locks held.
+ *
+ * @return a string identifying this lock, as well as its lock state
+ */
+ public String toString() {
+ long s = state;
+ return super.toString() +
+ ((s & ABITS) == 0L ? "[Unlocked]" :
+ (s & WBIT) != 0L ? "[Write-locked]" :
+ "[Read-locks:" + getReadLockCount(s) + "]");
+ }
+
+ // views
+
+ /**
* Returns a plain {@link Lock} view of this StampedLock in which
* the {@link Lock#lock} method is mapped to {@link #readLock},
* and similarly for other methods. The returned Lock does not
@@ -879,6 +911,12 @@ public class StampedLock implements java
}
}
+ private void readObject(java.io.ObjectInputStream s)
+ throws java.io.IOException, ClassNotFoundException {
+ s.defaultReadObject();
+ state = ORIGIN; // reset to unlocked state
+ }
+
// internals
/**
@@ -886,10 +924,11 @@ public class StampedLock implements java
* access bits value to RBITS, indicating hold of spinlock,
* then updating, then releasing.
*
- * @param s, assumed that (s & ABITS) >= RFULL
+ * @param s a reader overflow stamp: (s & ABITS) >= RFULL
* @return new stamp on success, else zero
*/
private long tryIncReaderOverflow(long s) {
+ // assert (s & ABITS) >= RFULL;
if ((s & ABITS) == RFULL) {
if (U.compareAndSwapLong(this, STATE, s, s | RBITS)) {
++readerOverflow;
@@ -906,10 +945,11 @@ public class StampedLock implements java
/**
* Tries to decrement readerOverflow.
*
- * @param s, assumed that (s & ABITS) >= RFULL
+ * @param s a reader overflow stamp: (s & ABITS) >= RFULL
* @return new stamp on success, else zero
*/
private long tryDecReaderOverflow(long s) {
+ // assert (s & ABITS) >= RFULL;
if ((s & ABITS) == RFULL) {
if (U.compareAndSwapLong(this, STATE, s, s | RBITS)) {
int r; long next;
@@ -929,7 +969,7 @@ public class StampedLock implements java
return 0L;
}
- /*
+ /**
* Wakes up the successor of h (normally whead). This is normally
* just h.next, but may require traversal from wtail if next
* pointers are lagging. This may fail to wake up an acquiring
@@ -1030,14 +1070,17 @@ public class StampedLock implements java
if (deadline == 0L)
time = 0L;
else if ((time = deadline - System.nanoTime()) <= 0L)
- return cancelWaiter(node, null, false);
- node.thread = Thread.currentThread();
+ return cancelWaiter(node, node, false);
+ Thread wt = Thread.currentThread();
+ U.putObject(wt, PARKBLOCKER, this); // emulate LockSupport.park
+ node.thread = wt;
if (node.prev == p && p.status == WAITING && // recheck
(p != whead || (state & ABITS) != 0L))
U.park(false, time);
node.thread = null;
+ U.putObject(wt, PARKBLOCKER, null);
if (interruptible && Thread.interrupted())
- return cancelWaiter(node, null, true);
+ return cancelWaiter(node, node, true);
}
}
}
@@ -1100,8 +1143,6 @@ public class StampedLock implements java
node.cowait = p.cowait, node)) {
node.thread = Thread.currentThread();
for (long time;;) {
- if (interruptible && Thread.interrupted())
- return cancelWaiter(node, p, true);
if (deadline == 0L)
time = 0L;
else if ((time = deadline - System.nanoTime()) <= 0L)
@@ -1113,9 +1154,14 @@ public class StampedLock implements java
node.thread = null;
break;
}
+ Thread wt = Thread.currentThread();
+ U.putObject(wt, PARKBLOCKER, this);
if (node.thread == null) // must recheck
break;
U.park(false, time);
+ U.putObject(wt, PARKBLOCKER, null);
+ if (interruptible && Thread.interrupted())
+ return cancelWaiter(node, p, true);
}
group = p;
}
@@ -1170,16 +1216,141 @@ public class StampedLock implements java
if (deadline == 0L)
time = 0L;
else if ((time = deadline - System.nanoTime()) <= 0L)
- return cancelWaiter(node, null, false);
- node.thread = Thread.currentThread();
+ return cancelWaiter(node, node, false);
+ Thread wt = Thread.currentThread();
+ U.putObject(wt, PARKBLOCKER, this);
+ node.thread = wt;
if (node.prev == p && p.status == WAITING &&
(p != whead || (state & ABITS) != WBIT))
U.park(false, time);
node.thread = null;
+ U.putObject(wt, PARKBLOCKER, null);
if (interruptible && Thread.interrupted())
- return cancelWaiter(node, null, true);
+ return cancelWaiter(node, node, true);
+ }
+ }
+ }
+
+ /**
+ * If node non-null, forces cancel status and unsplices it from
+ * queue if possible and wakes up any cowaiters (of the node, or
+ * group, as applicable), and in any case helps release current
+ * first waiter if lock is free. (Calling with null arguments
+ * serves as a conditional form of release, which is not currently
+ * needed but may be needed under possible future cancellation
+ * policies). This is a variant of cancellation methods in
+ * AbstractQueuedSynchronizer (see its detailed explanation in AQS
+ * internal documentation).
+ *
+ * @param node if nonnull, the waiter
+ * @param group either node or the group node is cowaiting with
+ * @param interrupted if already interrupted
+ * @return INTERRUPTED if interrupted or Thread.interrupted, else zero
+ */
+ private long cancelWaiter(WNode node, WNode group, boolean interrupted) {
+ if (node != null && group != null) {
+ Thread w;
+ node.status = CANCELLED;
+ node.thread = null;
+ // unsplice cancelled nodes from group
+ for (WNode p = group, q; (q = p.cowait) != null;) {
+ if (q.status == CANCELLED)
+ U.compareAndSwapObject(p, WNEXT, q, q.next);
+ else
+ p = q;
+ }
+ if (group == node) {
+ WNode r; // detach and wake up uncancelled co-waiters
+ while ((r = node.cowait) != null) {
+ if (U.compareAndSwapObject(node, WCOWAIT, r, r.cowait) &&
+ (w = r.thread) != null) {
+ r.thread = null;
+ U.unpark(w);
+ }
+ }
+ for (WNode pred = node.prev; pred != null; ) { // unsplice
+ WNode succ, pp; // find valid successor
+ while ((succ = node.next) == null ||
+ succ.status == CANCELLED) {
+ WNode q = null; // find successor the slow way
+ for (WNode t = wtail; t != null && t != node; t = t.prev)
+ if (t.status != CANCELLED)
+ q = t; // don't link if succ cancelled
+ if (succ == q || // ensure accurate successor
+ U.compareAndSwapObject(node, WNEXT,
+ succ, succ = q)) {
+ if (succ == null && node == wtail)
+ U.compareAndSwapObject(this, WTAIL, node, pred);
+ break;
+ }
+ }
+ if (pred.next == node) // unsplice pred link
+ U.compareAndSwapObject(pred, WNEXT, node, succ);
+ if (succ != null && (w = succ.thread) != null) {
+ succ.thread = null;
+ U.unpark(w); // wake up succ to observe new pred
+ }
+ if (pred.status != CANCELLED || (pp = pred.prev) == null)
+ break;
+ node.prev = pp; // repeat if new pred wrong/cancelled
+ U.compareAndSwapObject(pp, WNEXT, pred, succ);
+ pred = pp;
+ }
}
}
+ WNode h; // Possibly release first waiter
+ while ((h = whead) != null) {
+ long s; WNode q; // similar to release() but check eligibility
+ if ((q = h.next) == null || q.status == CANCELLED) {
+ for (WNode t = wtail; t != null && t != h; t = t.prev)
+ if (t.status <= 0)
+ q = t;
+ }
+ if (h == whead) {
+ if (q != null && h.status == 0 &&
+ ((s = state) & ABITS) != WBIT && // waiter is eligible
+ (s == 0L || q.mode == RMODE))
+ release(h);
+ break;
+ }
+ }
+ return (interrupted || Thread.interrupted()) ? INTERRUPTED : 0L;
+ }
+
+ // Unsafe mechanics
+ private static final sun.misc.Unsafe U;
+ private static final long STATE;
+ private static final long WHEAD;
+ private static final long WTAIL;
+ private static final long WNEXT;
+ private static final long WSTATUS;
+ private static final long WCOWAIT;
+ private static final long PARKBLOCKER;
+
+ static {
+ try {
+ U = getUnsafe();
+ Class> k = StampedLock.class;
+ Class> wk = WNode.class;
+ STATE = U.objectFieldOffset
+ (k.getDeclaredField("state"));
+ WHEAD = U.objectFieldOffset
+ (k.getDeclaredField("whead"));
+ WTAIL = U.objectFieldOffset
+ (k.getDeclaredField("wtail"));
+ WSTATUS = U.objectFieldOffset
+ (wk.getDeclaredField("status"));
+ WNEXT = U.objectFieldOffset
+ (wk.getDeclaredField("next"));
+ WCOWAIT = U.objectFieldOffset
+ (wk.getDeclaredField("cowait"));
+ Class> tk = Thread.class;
+ PARKBLOCKER = U.objectFieldOffset
+ (tk.getDeclaredField("parkBlocker"));
+
+ } catch (Exception e) {
+ throw new Error(e);
+ }
}
/**