Class StampedLockDetector

java.lang.Object
se.deversity.asynctest.diagnostics.StampedLockDetector

public class StampedLockDetector extends Object
Detects StampedLock misuse:
  • an optimistic read whose stamp the same thread never passed to validate();
  • a validate() that failed and was followed by neither a read lock, a write lock nor a retried optimistic read, on the same thread and the same lock instance;
  • a read or write stamp recorded as acquired and never recorded as released, on a lock that is still held when the run is analysed;
  • a read stamp released again after its recorded holds had all come back, while another reader still held the lock.

A failed validate() is not itself a finding. StampedLock exists for the case where a writer intervenes, and the documented answer is to fall back to readLock() or to retry the optimistic read; reporting the failure would fire stochastically on exactly the code that handles it correctly. The finding is a failed validation that is followed by neither, on the same thread and lock, which is the shape in which the stale value was used as read. A zero stamp from tryOptimisticRead() (the lock was write-held) is treated the same way: it can never validate, so it needs the same fallback.

A leak is decided by asking the lock. An acquisition nobody matched with recordUnlock(java.util.concurrent.locks.StampedLock, java.lang.String, long) is reported only while StampedLock.isWriteLocked() or StampedLock.isReadLocked() still says so at analysis, and a recordStampNotReleased(java.lang.String, long) declaration stands in for the unmatched acquisition under the same condition. Neither is enough alone: an unmatched record on a free lock is a gap in the recording, and a declaration on a free lock is contradicted by the lock (#588). A mode conversion recorded with recordConversion(java.util.concurrent.locks.StampedLock, java.lang.String, long, long) moves the outstanding acquisition to the stamp the conversion returned, so a converted hold that leaks is counted against the stamp the body still has (#604).

Matching is per thread and per lock instance, never per lock name and never on counts pooled across threads: two locks that share a label keep separate state, and validations on one thread do not cancel a read another thread never validated. Worker threads are pooled across invocation rounds, so markInvocationStart() seals whatever a round left unvalidated or unsettled; a read lock taken in a later round is never the fallback for a validation that failed in an earlier one.

Wrong stamps (#604). The lock refuses most of them itself, with IllegalMonitorStateException in the caller's own thread: a read stamp passed to unlockWrite, a write stamp passed to unlockRead, and a write stamp released twice. Those are not reported here. The one it accepts is a read stamp released again: unlockRead checks only the stamp's version, so while any other reader holds the lock the repeated release takes that reader's hold, and the exception surfaces later in the victim's thread, if at all. That is reported when the lock corroborates it: after an unlock that matched no outstanding recorded acquisition, StampedLock.getReadLockCount() is below the number of recorded read holds still outstanding. A release whose acquisition was never recorded cannot satisfy that, so a gap in the recording stays silent. Releasing a stamp from a thread other than the one that took it is legal for StampedLock, which has no owner, and is not a finding. Boundary: an acquisition recorded but released through a path that was not recorded, followed on the same lock by a recorded release of a hold that was never recorded, reads as a repeated release.

  • Constructor Details

    • StampedLockDetector

      public StampedLockDetector()
  • Method Details

    • registerLock

      public void registerLock(StampedLock lock, String name)
      Register a StampedLock for monitoring.

      Registration is optional: every record method registers a lock it has not seen under the name it was given. Registering first only fixes the label.

      Parameters:
      lock - the lock being recorded, tracked by identity rather than equality
      name - a label identifying the lock in the report
    • recordOptimisticRead

      public void recordOptimisticRead(StampedLock lock, String lockName, long stamp)
      Record an optimistic read stamp acquisition.
      Parameters:
      lock - the lock being recorded, tracked by identity rather than equality
      lockName - a label identifying the lock in the report
      stamp - the stamp returned by the StampedLock operation
    • recordOptimisticValidation

      public void recordOptimisticValidation(StampedLock lock, String lockName, long stamp, boolean validated)
      Record validation of optimistic read.
      Parameters:
      lock - the lock being recorded, tracked by identity rather than equality
      lockName - a label identifying the lock in the report
      stamp - the stamp returned by the StampedLock operation
      validated - the validated flag
    • recordReadLock

      public void recordReadLock(StampedLock lock, String lockName, long stamp)
      Record a read lock acquisition.
      Parameters:
      lock - the lock being recorded, tracked by identity rather than equality
      lockName - a label identifying the lock in the report
      stamp - the stamp returned by the StampedLock operation; zero, as tryReadLock returns when it fails, is not an acquisition
    • recordWriteLock

      public void recordWriteLock(StampedLock lock, String lockName, long stamp)
      Record a write lock acquisition.
      Parameters:
      lock - the lock being recorded, tracked by identity rather than equality
      lockName - a label identifying the lock in the report
      stamp - the stamp returned by the StampedLock operation; zero, as tryWriteLock returns when it fails, is not an acquisition
    • recordUnlock

      public void recordUnlock(StampedLock lock, String lockName, long stamp)
      Record a lock release.

      Record the release after the unlock call. A read stamp released again once its recorded holds have all come back is reported when the lock corroborates it (see the class javadoc); recorded before the unlock, that release cannot yet be seen in the lock's reader count.

      Parameters:
      lock - the lock being recorded, tracked by identity rather than equality
      lockName - a label identifying the lock in the report
      stamp - the stamp returned by the StampedLock operation
    • recordConversion

      public void recordConversion(StampedLock lock, String lockName, long fromStamp, long toStamp)
      Record a mode conversion: tryConvertToWriteLock, tryConvertToReadLock or tryConvertToOptimisticRead.

      The kind of each stamp is read from the stamp itself (StampedLock.isOptimisticReadStamp(long), StampedLock.isLockStamp(long)), so the caller does not say which conversion it made:

      • from a read or write stamp, a successful conversion gives that stamp up, and a lock stamp it returns is tracked in its place, so a converted hold that leaks is counted against the stamp the body still has;
      • from an optimistic stamp, the conversion is a validation: it succeeds only for a stamp that still validates, and a failed one needs the same fallback as a failed validate();
      • a zero toStamp is a failed conversion, and whatever fromStamp held is still held;
      • the optimistic stamp a downgrade returns is not tracked as a read needing validation: what was read under the lock is still valid, and the conversion does not say whether anything is read after it.
      Parameters:
      lock - the lock being recorded, tracked by identity rather than equality
      lockName - a label identifying the lock in the report
      fromStamp - the stamp passed to the conversion
      toStamp - the stamp the conversion returned, zero if it failed
      Since:
      1.12.1
    • recordStampNotReleased

      public void recordStampNotReleased(String lockName, long stamp)
      Declare that a stamp on the lock registered under this name was not released.

      A declaration is corroborated, not taken on trust: it is reported only if a lock registered under lockName is still read- or write-held when the run is analysed. Prefer recording the acquisition itself, which the detector matches against recordUnlock(java.util.concurrent.locks.StampedLock, java.lang.String, long) without any declaration.

      Parameters:
      lockName - a label identifying the lock in the report
      stamp - the stamp returned by the StampedLock operation (informational)
    • markInvocationStart

      public void markInvocationStart()
      Marks the start of a new invocation round.

      Called by ConcurrencyRunner before each round, after the previous round's workers have finished. Optimistic reads a round left unvalidated, and failed validations it never fell back from, are sealed as findings, so a pooled worker's lock acquisition in the next round cannot settle them.

      Since:
      1.12.1
    • analyze

      Analyze StampedLock usage and return report.
      Returns:
      the findings this detector collected during the run