A StampedLock That Never Used Its Stamp

How a Lock, a Flag, and a Concurrent Set Still Lost Updates

 ยท 15 min
Part of the collection Notes From Building a Profiler

There’s a moment in a code review where somebody uses a StampedLock, and everyone silently assumes they know something the rest of us don’t. The stamps, the explicit unlock with a token, the whole ceremony of it reads like code written by someone who made an informed decision by measuring.

I know, because I was that somebody, but I hadn’t measured anything.

This article follows a StampedLock from my own code, from the commit that added it to the one that deleted it. For an overview of Java’s locking options, What synchronized Actually Does compares them in detail, StampedLock included.


A Stamp Used as a Receipt

The lock lives in a small request-tracing library I built for our Apache Tapestry apps, in a class that collects per-method call statistics displayed on a debug page. While going back to profile the library itself, I noticed that its memory grew without bound, one long per recorded call.

Every single call site in that class looks like this:

java
long stamp = this.lock.writeLock();
try {
    // ...
}
finally {
    this.lock.unlockWrite(stamp);
}

Never a read lock.
Never a tryOptimisticRead().

The stamp was there, all right, but only as a receipt to hand back at unlock.

That’s just a ReentrantLock with a token, minus the reentrancy.

And it turned out to be the least of that class’s problems.


What StampedLock Is Actually For

StampedLock arrived in Java 8 (JEP 155, JDK-8005697) with three modes: writing, reading, and optimistic reading. The third is why the class exists.

A regular read lock lets many readers in at once, but acquiring it is still a write to shared memory. Every reader CASes a shared counter on the way in and again on the way out. That’s true for ReentrantReadWriteLock, Java’s read/write lock since Java 5 (JSR 166), and just as true for StampedLock’s own readLock(). With enough concurrent readers, that counter becomes a contended cache line, and a read-mostly workload serializes on the bookkeeping for reads that never conflicted with anything.

StampedLock#tryOptimisticRead() skips that bookkeeping entirely, because it writes nothing at all:

java
// OPTIMISTIC: no shared write, no cache-line bouncing
long stamp = lock.tryOptimisticRead();

// READ INTO LOCALS ONLY, the fields may be changing underneath us
int localX = this.x;
int localY = this.y;

if (lock.validate(stamp) == false) {
    // A writer intervened so that the locals may be inconsistent. Start over, properly.
    stamp = lock.readLock();
    try {
        localX = this.x;
        localY = this.y;
    }
    finally {
        lock.unlockRead(stamp);
    }
}

// Only now are localX and localY safe to use

That trick requires discipline: read into locals and nothing else, never follow a reference read optimistically, and put nothing in the block that can’t safely run twice. And the fallback isn’t optional, it’s a path we have to write. While a writer holds the lock, tryOptimisticRead() returns 0, and validate(0) is always false.

That ceremony is the price of admission for the one feature that makes StampedLock worth choosing.

Skip the feature, and all we kept is the price.


Three Mechanisms, One Cache

Here’s the part of the statistics class that matters:

java
private final Map<Method, LongGrowingBuffer> methodExecutions = new ConcurrentHashMap<>();
private final StampedLock                    lock             = new StampedLock();
private final Set<CallStatistic>             statsCache       = ConcurrentHashMap.newKeySet();
private volatile boolean                     statsCacheValid  = false;

That’s three synchronization mechanisms for a single cache: a lock, a concurrent statsCache, and a volatile flag. Each one made sense on its own. The flag saves recomputing on every page view, the lock keeps two recomputes from interleaving, and the concurrent set means copying it never throws.

That’s not defense in depth… that’s uncertainty about the actual invariant, expressed as fields!

Here’s what the three paths through the class do with them:

java
public void addMethodCall(Method method, long executionTime) {
    this.methodExecutions.computeIfAbsent(method, k -> new LongGrowingBuffer())
                         .add(executionTime);
    this.statsCacheValid = false;  // NO LOCK
}

public Set<CallStatistic> statistics() {
    if (this.statsCacheValid == false) {
        recomputeStatistics();
    }
    return Set.copyOf(this.statsCache);  // NO LOCK
}

private void recomputeStatistics() {
    long stamp = this.lock.writeLock();
    try {
        if (this.statsCacheValid) {
            return;  // Double-check
        }
        this.statsCache.clear();
        // ... compute one CallStatistic per method into statsCache ...
        this.statsCacheValid = true;
    }
    finally {
        this.lock.unlockWrite(stamp);
    }
}

Only the recompute takes the lock, and with the double-check, that part is genuinely fine. The recording and read paths never touch it.

My initial design sounded fine, but it gave me two bugs, and both of them are invisible. Neither throws, and no dashboard will ever flag a count that’s just a little too low.

The Lost Invalidation

The recompute reads the buffers, then sets the flag to true, and nothing stops a recorded call from landing in between:

text
Thread 1 (recording)              Thread 2 (reading statistics)

                                  +-- writeLock() ---------------+
                                  | statsCache.clear()           |
                                  | read buffers: [1, 2]         |  <== 4711 not there yet
                                  |                              |
+---------------------------+     |                              |
| buffer.add(4711)          |     |                              |
| statsCacheValid = false   |     |                              |
+---------------------------+     |                              |
                                  |                              |
                                  | statsCacheValid = true       |  <== invalidation overwritten
                                  +-- unlockWrite() -------------+

The cache is now marked valid by thread 2, but it’s missing the call from thread 1. It stays wrong until the next recorded call flips the flag again, so the very last call before a quiet period can be the one that never shows up.

That window is narrow enough that waiting for it to happen by chance makes for a poor demo. Instead, in the accompanying repository, the code pauses thread 2 right after it reads the buffers, using two CountDownLatch instances, one-shot gates that a thread waits on until another opens them.

The latches don’t change what can happen, only when it happens:

text
broken (StampedLock + volatile flag): call 4711 LOST, statistics = [1, 2]
cached (compute-then-publish):        call 4711 present, statistics = [1, 2, 4711]

Repository: LostInvalidation.java

On a debug page, a missing call is a shrug. But nothing about this bug is specific to call statistics.

Any cache that’s invalidated by a flag and rebuilt from its source has the same window. Put it in front of permissions, and a revoked role keeps working until some unrelated change flips the flag again. Put it in front of feature flags or prices, and the change we just made silently doesn’t take effect.

And it won’t be there when someone goes looking. The next write heals the cache, so by the time anyone investigates, everything looks correct…

The Unguarded Copy

The second bug doesn’t need any latches to show up.

A reader checks the flag, sees a valid cache, and starts copying it. Meanwhile, a recorded call invalidates the cache, and another reader starts recomputing: clear(), then refill. The first reader is now copying a set that’s being emptied underneath it:

text
Reader A                    Recorder                   Reader B

valid? true
+-- Set.copyOf() ----+
|                    |      buffer.add(...)
|                    |      valid = false
|                    |                               valid? false
|                    |                               +-- writeLock() ------+
|                    |                               | statsCache.clear()  |  <== A is mid-copy
|                    |                               | ... refill          |
+--------------------+                               | valid = true        |
                                                     +-- unlockWrite() ----+
returns a partial set

The demo is just one thread recording calls and four threads reading statistics for two seconds. Since it never removes a call, any result that’s smaller than the same reader’s previous one is a copy of a half-rebuilt set.

text
broken (StampedLock + volatile flag): 427 torn reads out of 1328
cached (compute-then-publish):        0 torn reads out of 2401

Repository: UnguardedCopy.java

The numbers change with every run, anywhere from a tenth to a third of all reads, but the broken version never came out at zero for me.

To be fair, that’s four readers hammering a page that, in production, maybe gets opened a handful of times a day. The lost invalidation is the bug that actually bites, though. This one just shows how little the lock was guarding.

The lock protects the recomputation.
Nothing protects the cache.


Would Using the Lock Properly Have Helped?

So was this just me using a StampedLock wrong? Just add the optimistic read the class was built for, and we’re done?

No.

A read lock around Set.copyOf() would fix the unguarded copy, sure. But the lost invalidation happens on the recording path, and that path never touches the lock at all. To fix it with a lock, recording and recomputing would have to be mutually exclusive.

Recorders don’t conflict with each other so that they could share the lock, but the recompute needs it exclusively. In lock terms, that’s the read lock for every recorded call and the write lock for the recompute, the opposite of what the names might suggest. That puts the contended shared counter from earlier back on the hottest path, and a debug-page recompute blocks every recorder while it runs…

No lock mode fixes a problem in code that doesn’t take the lock.

And for a lock that couldn’t fix anything, I still paid the full price of StampedLock:

  • It is not reentrant.
    Calling writeLock() while already holding it doesn’t throw and doesn’t succeed. It just parks. Forever.

  • There is no Condition support.
    No await()/signal(), the Lock equivalent of wait()/notify(), so if the code ever needs it, the migration away isn’t mechanical.

  • The stamp is a real obligation.
    A wrong or stale write stamp throws an IllegalMonitorStateException, and the exception doesn’t say which line lost track of the token. Read stamps are even worse, as unlocking the same one twice can silently release another reader’s hold. Lose the stamp entirely and nothing throws at all, and the lock stays held.

  • There are no useful ownership queries.
    Calling isWriteLocked() only reports that the lock is held. Not by whom, and not whether it’s us.

The missing owner also shows up where it hurts most. A thread that deadlocked itself on a StampedLock appears in jcmd <pid> Thread.print -l as WAITING (parking), with no “Found one Java-level deadlock” section anywhere. The dump even names the lock it’s parked on, parking to wait for <0x...> (a java.util.concurrent.locks.StampedLock), but not who holds it. StampedLock doesn’t extend AbstractOwnableSynchronizer, so there’s no owner to report. The thread’s “Locked ownable synchronizers” reads - None, while it’s holding the very lock it’s waiting for.

Repository: SelfDeadlock.java, StampProbe.java

So what did all of that buy me?

Mutual exclusion around a block that runs on a debug statistics page, a handful of times a day.


What It Should Have Been

Writing down the actual invariant first would have saved all of this. So let’s do it now: a recorded call may be one page view late, but never more.

That’s it.

The original broke exactly that. A call that lost the race stayed missing until some unrelated call invalidated the cache again, and during a quiet period, that might be hours.

The cache was supposed to save us recomputing on every page view. But every single recorded call invalidated it, and calls are recorded constantly in a running app. By the time anybody opened the debug page, the cache was invalid anyway, so it rarely served a hit. What it did do was add a volatile write to every recorded call, on the hot path, for nothing.

A cache that never hits is just overhead, with extra bugs.

So I deleted it and simplified the code:

java
public Set<CallStatistic> statistics() {
    Set<CallStatistic> statistics = new HashSet<>();
    for (var entry : this.methodExecutions.entrySet()) {
        // EVERY READER computes its own, nothing shared
        CallStatistic stat = computeStatistics(entry.getKey(), entry.getValue());
        statistics.add(stat);
    }
    return Set.copyOf(statistics);  // Immutable for callers, same contract as before
}

No lock, no flag, no shared cache.

Every reader builds its own result from the recorded data, so there’s no shared result to tear and no invalidation to lose. A call that arrives while a page view is being built might miss that one view, but it’s guaranteed to be in the next. The StampedLock went with it, and so did the class’s own clear() method. Turns out nothing ever called that one.

Of course, that meant every debug page view paid for the full computation.

And that’s where the memory growth from the beginning comes back in. The buffers kept every single duration, one long per call, forever, so a median or p95 meant copying and sorting all of them. The cache never fixed that cost, it only tried to pay it less often.

So the same change replaced the growing buffers with fixed-size histograms: a fixed set of buckets per method, and recording a call increments one of them. Memory stays flat at about 18 KB per method, no matter how many calls come in, and percentiles come straight from the bucket counts, without any sorting. The price is precision: median and p95 are now approximations, within 0.8%, while count, min, max, and mean stay exact.

There’s a second cost, too: the statistics for different methods aren’t one consistent snapshot, because calls keep arriving while we iterate.

For a debug page, I believe both are completely fine. The requirement was never linearizability to begin with.

The best synchronization is the code we get to delete.

If We Do Need the Cache

Sometimes the computation really is expensive, and the cache has to stay. Then the invariant changes to: one thread recomputes, and everybody else reads a consistent snapshot that’s never more than a little stale.

That’s compute-then-publish. It isn’t read/write exclusion either, so a read/write lock still isn’t the right shape. Instead, let’s build it one problem at a time.

The unguarded copy happened because readers copied a set that a recompute was emptying. So let’s stop mutating it. A recompute builds a brand-new set and publishes it with a single volatile store:

java
private volatile Set<CallStatistic> stats = Set.of();  // immutable snapshot

public Set<CallStatistic> statistics() {
    // ... recompute if needed, see below ...
    return this.stats;  // Already immutable, so handing it out is free
}

A reader gets either the old snapshot or the new one, never a half-rebuilt one. No clear(), nothing to tear, and no defensive copy either.

Next, the lost invalidation. A boolean can’t tell a recompute which calls it has seen, so it happily overwrote an invalidation it never saw. A counter can:

java
private final    Object     recomputeLock = new Object();
private final    AtomicLong generation    = new AtomicLong();  // bumped per recorded call
private volatile long       computedAt    = -1;                // generation of the snapshot

private void recompute() {
    synchronized (this.recomputeLock) {

        // STEP 1: Read the generation BEFORE the buffers, not after.
        long seen = this.generation.get();
        if (this.computedAt == seen) {
            return;  // Somebody else already did the work
        }

        // STEP 2: Build a fresh immutable snapshot.
        Set<CallStatistic> snapshot = computeSnapshot();

        // STEP 3: Publish, and record which generation this snapshot represents.
        this.stats = snapshot;
        this.computedAt = seen;
    }
}

The recording side has to hold up its end, too: write the buffer first, then call generation.incrementAndGet(). Reversed, a recompute can claim a generation without seeing its call. And it has to be an AtomicLong: generation++ on a volatile long drops increments under exactly the concurrency we’re trying to count.

Capturing the generation before reading and bumping it only after writing closes the lost invalidation. If a call arrives mid-recompute, generation moves past seen, the snapshot is marked as belonging to the older generation, and the next reader recomputes.

That’s correct now, but it barely counts as a cache. Every recorded call bumps the generation, so under steady traffic nearly every read recomputes, and concurrent readers queue up behind recomputeLock, which is slower than no cache!

The invariant already allows a little staleness, so let’s put a number on it:

java
private static final long MAX_STALENESS = TimeUnit.SECONDS.toNanos(1);

private volatile long computedNanos = System.nanoTime() - MAX_STALENESS;  // first read recomputes

private boolean needsRecompute(long current) {
    return this.computedAt != current                                    // something changed...
           && System.nanoTime() - this.computedNanos >= MAX_STALENESS;  // ...and we're allowed to care
}

Both statistics() and the double-check in recompute() now ask needsRecompute() instead of comparing generations directly, and publish records computedNanos next to computedAt. A call can be late, but never by more than MAX_STALENESS.

Repository: FixedCache.java

It’s still a shared atomic write per recorded call, and an AtomicLong increment costs more than the volatile store it replaces. So it’s only worth it when the computation is expensive and the statistics are read often enough for a hit to matter, which for my debug page was never the case.

There’s a nice bit of irony here, though: a generation number checked after the fact is the same trick validate(stamp) plays.

We ended up with a stamp after all, just from an AtomicLong we own, instead of one StampedLock hands out.


Ceremony Is Not Rigor

None of that was StampedLock’s fault.

It’s an excellent lock, and tryOptimisticRead() is one of the sharpest tools in java.util.concurrent. For state that’s genuinely read-mostly and spread across several mutable fields, like coordinates or a sensor reading that changes too often to allocate a new snapshot every time, skipping that shared counter on every read is a real win. At least once a profiler says the read lock is where the time goes.

The lesson also isn’t “use synchronized and stop reading about concurrency.” It isn’t even “don’t use StampedLock.”

The bug was that I picked a lock before writing down what needed protecting. The long stamp at every call site looked like rigor, and it was doing the opposite: three overlapping mechanisms, an invariant nobody had stated, and a lock guarding against the one race that wasn’t going to happen.

Once the invariant was on paper, the answer wasn’t a better lock. It was no lock, and no cache.

So the next time you see a StampedLock in a diff, ask where the tryOptimisticRead() is. If it isn’t there, ask the better question: what is this lock protecting, and does every path that touches that state actually take it?

And ask it about your own code first.


Resources