63  * is released, either the longest-waiting single writer thread will
  64  * be assigned the write lock, or if there is a group of reader threads
  65  * waiting longer than all waiting writer threads, that group will be
  66  * assigned the read lock.
  67  *
  68  * <p>A thread that tries to acquire a fair read lock (non-reentrantly)
  69  * will block if either the write lock is held, or there is a waiting
  70  * writer thread. The thread will not acquire the read lock until
  71  * after the oldest currently waiting writer thread has acquired and
  72  * released the write lock. Of course, if a waiting writer abandons
  73  * its wait, leaving one or more reader threads as the longest waiters
  74  * in the queue with the write lock free, then those readers will be
  75  * assigned the read lock.
  76  *
  77  * <p>A thread that tries to acquire a fair write lock (non-reentrantly)
  78  * will block unless both the read lock and write lock are free (which
  79  * implies there are no waiting threads).  (Note that the non-blocking
  80  * {@link ReadLock#tryLock()} and {@link WriteLock#tryLock()} methods
  81  * do not honor this fair setting and will immediately acquire the lock
  82  * if it is possible, regardless of waiting threads.)
  83  * <p>
  84  * </dl>
  85  *
  86  * <li><b>Reentrancy</b>
  87  *
  88  * <p>This lock allows both readers and writers to reacquire read or
  89  * write locks in the style of a {@link ReentrantLock}. Non-reentrant
  90  * readers are not allowed until all write locks held by the writing
  91  * thread have been released.
  92  *
  93  * <p>Additionally, a writer can acquire the read lock, but not
  94  * vice-versa.  Among other applications, reentrancy can be useful
  95  * when write locks are held during calls or callbacks to methods that
  96  * perform reads under read locks.  If a reader tries to acquire the
  97  * write lock it will never succeed.
  98  *
  99  * <li><b>Lock downgrading</b>
 100  * <p>Reentrancy also allows downgrading from the write lock to a read lock,
 101  * by acquiring the write lock, then the read lock and then releasing the
 102  * write lock. However, upgrading from a read lock to the write lock is
 103  * <b>not</b> possible.

  63  * is released, either the longest-waiting single writer thread will
  64  * be assigned the write lock, or if there is a group of reader threads
  65  * waiting longer than all waiting writer threads, that group will be
  66  * assigned the read lock.
  67  *
  68  * <p>A thread that tries to acquire a fair read lock (non-reentrantly)
  69  * will block if either the write lock is held, or there is a waiting
  70  * writer thread. The thread will not acquire the read lock until
  71  * after the oldest currently waiting writer thread has acquired and
  72  * released the write lock. Of course, if a waiting writer abandons
  73  * its wait, leaving one or more reader threads as the longest waiters
  74  * in the queue with the write lock free, then those readers will be
  75  * assigned the read lock.
  76  *
  77  * <p>A thread that tries to acquire a fair write lock (non-reentrantly)
  78  * will block unless both the read lock and write lock are free (which
  79  * implies there are no waiting threads).  (Note that the non-blocking
  80  * {@link ReadLock#tryLock()} and {@link WriteLock#tryLock()} methods
  81  * do not honor this fair setting and will immediately acquire the lock
  82  * if it is possible, regardless of waiting threads.)

  83  * </dl>
  84  *
  85  * <li><b>Reentrancy</b>
  86  *
  87  * <p>This lock allows both readers and writers to reacquire read or
  88  * write locks in the style of a {@link ReentrantLock}. Non-reentrant
  89  * readers are not allowed until all write locks held by the writing
  90  * thread have been released.
  91  *
  92  * <p>Additionally, a writer can acquire the read lock, but not
  93  * vice-versa.  Among other applications, reentrancy can be useful
  94  * when write locks are held during calls or callbacks to methods that
  95  * perform reads under read locks.  If a reader tries to acquire the
  96  * write lock it will never succeed.
  97  *
  98  * <li><b>Lock downgrading</b>
  99  * <p>Reentrancy also allows downgrading from the write lock to a read lock,
 100  * by acquiring the write lock, then the read lock and then releasing the
 101  * write lock. However, upgrading from a read lock to the write lock is
 102  * <b>not</b> possible.