Class StampedLockDetector
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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic classReport class for StampedLock analysis. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionanalyze()Analyze StampedLock usage and return report.voidMarks the start of a new invocation round.voidrecordConversion(StampedLock lock, String lockName, long fromStamp, long toStamp) Record a mode conversion:tryConvertToWriteLock,tryConvertToReadLockortryConvertToOptimisticRead.voidrecordOptimisticRead(StampedLock lock, String lockName, long stamp) Record an optimistic read stamp acquisition.voidrecordOptimisticValidation(StampedLock lock, String lockName, long stamp, boolean validated) Record validation of optimistic read.voidrecordReadLock(StampedLock lock, String lockName, long stamp) Record a read lock acquisition.voidrecordStampNotReleased(String lockName, long stamp) Declare that a stamp on the lock registered under this name was not released.voidrecordUnlock(StampedLock lock, String lockName, long stamp) Record a lock release.voidrecordWriteLock(StampedLock lock, String lockName, long stamp) Record a write lock acquisition.voidregisterLock(StampedLock lock, String name) Register a StampedLock for monitoring.
-
Constructor Details
-
StampedLockDetector
public StampedLockDetector()
-
-
Method Details
-
registerLock
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 equalityname- a label identifying the lock in the report
-
recordOptimisticRead
Record an optimistic read stamp acquisition.- Parameters:
lock- the lock being recorded, tracked by identity rather than equalitylockName- a label identifying the lock in the reportstamp- the stamp returned by theStampedLockoperation
-
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 equalitylockName- a label identifying the lock in the reportstamp- the stamp returned by theStampedLockoperationvalidated- thevalidatedflag
-
recordReadLock
Record a read lock acquisition.- Parameters:
lock- the lock being recorded, tracked by identity rather than equalitylockName- a label identifying the lock in the reportstamp- the stamp returned by theStampedLockoperation; zero, astryReadLockreturns when it fails, is not an acquisition
-
recordWriteLock
Record a write lock acquisition.- Parameters:
lock- the lock being recorded, tracked by identity rather than equalitylockName- a label identifying the lock in the reportstamp- the stamp returned by theStampedLockoperation; zero, astryWriteLockreturns when it fails, is not an acquisition
-
recordUnlock
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 equalitylockName- a label identifying the lock in the reportstamp- the stamp returned by theStampedLockoperation
-
recordConversion
Record a mode conversion:tryConvertToWriteLock,tryConvertToReadLockortryConvertToOptimisticRead.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
toStampis a failed conversion, and whateverfromStampheld 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 equalitylockName- a label identifying the lock in the reportfromStamp- the stamp passed to the conversiontoStamp- the stamp the conversion returned, zero if it failed- Since:
- 1.12.1
-
recordStampNotReleased
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
lockNameis still read- or write-held when the run is analysed. Prefer recording the acquisition itself, which the detector matches againstrecordUnlock(java.util.concurrent.locks.StampedLock, java.lang.String, long)without any declaration.- Parameters:
lockName- a label identifying the lock in the reportstamp- the stamp returned by theStampedLockoperation (informational)
-
markInvocationStart
public void markInvocationStart()Marks the start of a new invocation round.Called by
ConcurrencyRunnerbefore 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
-