Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8187942

Add StampedLock stamp inspection methods

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: None
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      source
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      It's hard to imagine breaking any user subclasses
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Add static StampedLock stamp inspection methods that don't inspect lock state.

      Problem

      StampedLock has methods to upgrade an optimistic or read lock, but there's no way in a finally block to surely roll back any lock acquisition without extra bookkeeping with local flags or unnecessary volatile operations on the lock.

      We should fix this so that users can do

      long stamp = sl.tryOptimisticRead(); 
      try { 
        ... 
        stamp = sl.tryConvertToWriteLock(stamp); 
        ... 
      } finally { 
       if (StampedLock.isWriteLockStamp(stamp)) 
         sl.unlockWrite(stamp); 
      } 

      Solution

      Add the 4 obvious easy stamp inspection methods.

      Specification

      
          /**
           * Tells whether a stamp represents holding a lock exclusively.
           * This method may be useful in conjunction with
           * {@link #tryConvertToWriteLock}, for example: <pre> {@code
           * long stamp = sl.tryOptimisticRead();
           * try {
           *   ...
           *   stamp = sl.tryConvertToWriteLock(stamp);
           *   ...
           * } finally {
           *   if (StampedLock.isWriteLockStamp(stamp))
           *     sl.unlockWrite(stamp);
           * }}</pre>
           *
           * @param stamp a stamp returned by a previous StampedLock operation
           * @return {@code true} if the stamp was returned by a successful
           *   write-lock operation
           */
          public static boolean isWriteLockStamp(long stamp) {
              return (stamp & ABITS) == WBIT;
          }
      
          /**
           * Tells whether a stamp represents holding a lock non-exclusively.
           * This method may be useful in conjunction with
           * {@link #tryConvertToReadLock}, for example: <pre> {@code
           * long stamp = sl.tryOptimisticRead();
           * try {
           *   ...
           *   stamp = sl.tryConvertToReadLock(stamp);
           *   ...
           * } finally {
           *   if (StampedLock.isReadLockStamp(stamp))
           *     sl.unlockRead(stamp);
           * }}</pre>
           *
           * @param stamp a stamp returned by a previous StampedLock operation
           * @return {@code true} if the stamp was returned by a successful
           *   read-lock operation
           */
          public static boolean isReadLockStamp(long stamp) {
              return (stamp & RBITS) != 0L;
          }
      
          /**
           * Tells whether a stamp represents holding a lock.
           * This method may be useful in conjunction with
           * {@link #tryConvertToReadLock} and {@link #tryConvertToWriteLock},
           * for example: <pre> {@code
           * long stamp = sl.tryOptimisticRead();
           * try {
           *   ...
           *   stamp = sl.tryConvertToReadLock(stamp);
           *   ...
           *   stamp = sl.tryConvertToWriteLock(stamp);
           *   ...
           * } finally {
           *   if (StampedLock.isLockStamp(stamp))
           *     sl.unlock(stamp);
           * }}</pre>
           *
           * @param stamp a stamp returned by a previous StampedLock operation
           * @return {@code true} if the stamp was returned by a successful
           *   read-lock or write-lock operation
           */
          public static boolean isLockStamp(long stamp) {
              return (stamp & ABITS) != 0L;
          }
      
          /**
           * Tells whether a stamp represents a successful optimistic read.
           *
           * @param stamp a stamp returned by a previous StampedLock operation
           * @return {@code true} if the stamp was returned by a successful
           *   optimistic read operation, that is, a non-zero return from
           *   {@link #tryOptimisticRead()} or
           *   {@link #tryConvertToOptimisticRead(long)}
           */
          public static boolean isOptimisticReadStamp(long stamp) {
              return (stamp & ABITS) == 0L && stamp != 0L;
          }

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              martin Martin Buchholz
              Reporter:
              martin Martin Buchholz
              Reviewed By:
              Doug Lea
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: