Add lru-cache module: LinkedHashMap and hand-rolled DLL LRU, coarse-lock/striped thread-safe variants, broken ReadWriteLock demo, Caffeine reference, 43 tests, JMH harness

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017ic4b4VQVEJWetTT1dYzyJ
This commit is contained in:
2026-10-29 05:52:27 +00:00
co-authored by Claude Sonnet 5.5
parent 4a376b94e9
commit 0457cf4bfb
31 changed files with 1425 additions and 0 deletions
@@ -0,0 +1,88 @@
package com.ankurm.interviewlab.lrucache;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ThreadLocalRandom;
import java.util.concurrent.atomic.AtomicInteger;
/**
* Hammers {@link BrokenReadWriteLockLruCache} (read lock around get) and, for contrast,
* {@link SynchronizedLruCache} with the same workload, then runs the structural invariant check.
* The broken result is a MEASUREMENT of a race: it depends on timing and core count and can
* (rarely) come out clean. Run it a few times; run-all.sh runs five rounds.
*/
public final class BrokenLockDemo {
static final int THREADS = 4, OPS = 400_000, CAPACITY = 64, KEYS = 128;
interface Checked extends LruCache<Integer, Integer> { void checkInvariants(); }
public static void main(String[] args) throws Exception {
System.out.println("cores=" + Runtime.getRuntime().availableProcessors()
+ " threads=" + THREADS + " opsPerThread=" + OPS + " capacity=" + CAPACITY + " keys=" + KEYS);
System.out.println("workload: 90% get, 10% put, uniform random keys");
System.out.println();
for (int round = 1; round <= 5; round++) {
System.out.println("round " + round);
report(" ReadWriteLock, get under READ lock ", wrap(new BrokenReadWriteLockLruCache<>(CAPACITY)));
report(" synchronized (correct) ", wrap(new SynchronizedLruCache<>(CAPACITY)));
}
}
static Checked wrap(BrokenReadWriteLockLruCache<Integer, Integer> c) {
return new Checked() {
public Integer get(Integer k) { return c.get(k); }
public void put(Integer k, Integer v) { c.put(k, v); }
public int size() { return c.size(); }
public int capacity() { return c.capacity(); }
public java.util.List<Integer> keysLruFirst() { return c.keysLruFirst(); }
public void checkInvariants() { c.checkInvariants(); }
};
}
static Checked wrap(SynchronizedLruCache<Integer, Integer> c) {
return new Checked() {
public Integer get(Integer k) { return c.get(k); }
public void put(Integer k, Integer v) { c.put(k, v); }
public int size() { return c.size(); }
public int capacity() { return c.capacity(); }
public java.util.List<Integer> keysLruFirst() { return c.keysLruFirst(); }
public void checkInvariants() { c.checkInvariants(); }
};
}
static void report(String label, Checked cache) throws Exception {
AtomicInteger exceptions = new AtomicInteger();
String[] firstException = new String[1];
CountDownLatch go = new CountDownLatch(1);
Thread[] ts = new Thread[THREADS];
for (int t = 0; t < THREADS; t++) {
ts[t] = new Thread(() -> {
try { go.await(); } catch (InterruptedException e) { return; }
ThreadLocalRandom r = ThreadLocalRandom.current();
for (int i = 0; i < OPS; i++) {
int k = r.nextInt(KEYS);
try {
if (r.nextInt(10) == 0) cache.put(k, k); else cache.get(k);
} catch (Throwable e) {
if (exceptions.getAndIncrement() == 0) firstException[0] = e.toString();
return;
}
}
});
ts[t].start();
}
go.countDown();
for (Thread t : ts) t.join();
String verdict;
try {
cache.checkInvariants();
verdict = "invariants OK";
} catch (Throwable e) {
verdict = "INVARIANT BROKEN: " + e.getMessage();
}
System.out.println(label + " worker exceptions=" + exceptions.get()
+ (firstException[0] != null ? " (first: " + firstException[0] + ")" : "")
+ "; size=" + safeSize(cache) + "/" + CAPACITY + "; " + verdict);
}
static String safeSize(Checked c) { return String.valueOf(c.size()); }
}
@@ -0,0 +1,30 @@
package com.ankurm.interviewlab.lrucache;
import java.util.List;
import java.util.concurrent.locks.ReentrantReadWriteLock;
/**
* DELIBERATELY BROKEN. The tempting "reads are common, so use a ReadWriteLock" design.
* {@code get} takes only the READ lock, so several threads run {@code delegate.get} at once, and
* {@code get} rewrites four list pointers. Concurrent pointer rewrites corrupt the list.
* {@link BrokenLockDemo} shows what that looks like. Never use this class.
*/
public final class BrokenReadWriteLockLruCache<K, V> implements LruCache<K, V> {
private final HashMapLruCache<K, V> delegate;
private final ReentrantReadWriteLock rw = new ReentrantReadWriteLock();
public BrokenReadWriteLockLruCache(int capacity) { this.delegate = new HashMapLruCache<>(capacity); }
@Override public V get(K key) {
rw.readLock().lock(); // BUG: get() is a write to the recency list
try { return delegate.get(key); } finally { rw.readLock().unlock(); }
}
@Override public void put(K key, V value) {
rw.writeLock().lock();
try { delegate.put(key, value); } finally { rw.writeLock().unlock(); }
}
@Override public int size() { return delegate.size(); }
@Override public int capacity() { return delegate.capacity(); }
@Override public List<K> keysLruFirst() { return delegate.keysLruFirst(); }
public void checkInvariants() { delegate.checkInvariants(); }
}
@@ -0,0 +1,35 @@
package com.ankurm.interviewlab.lrucache;
import com.github.benmanes.caffeine.cache.Cache;
import com.github.benmanes.caffeine.cache.Caffeine;
import java.util.List;
import java.util.Objects;
/**
* Adapter that lets Caffeine, the production answer, stand next to the hand-written caches in the
* tests and benchmark. Caffeine is a bounded cache, not a strict LRU: it uses the Window TinyLFU
* admission policy and does its bookkeeping asynchronously, so {@code size()} can briefly exceed the
* maximum until maintenance runs, and the victim is not always the least recently used key.
*/
public final class CaffeineLru<K, V> implements LruCache<K, V> {
private final Cache<K, V> cache;
private final int capacity;
/** @param sameThread true runs maintenance on the caller thread: deterministic, for tests. */
public CaffeineLru(int capacity, boolean sameThread) {
this.capacity = capacity;
Caffeine<Object, Object> b = Caffeine.newBuilder().maximumSize(capacity);
if (sameThread) b.executor(Runnable::run);
this.cache = b.build();
}
public CaffeineLru(int capacity) { this(capacity, false); }
@Override public V get(K key) { return cache.getIfPresent(Objects.requireNonNull(key)); }
@Override public void put(K key, V value) { cache.put(Objects.requireNonNull(key), Objects.requireNonNull(value)); }
@Override public int size() { cache.cleanUp(); return (int) cache.estimatedSize(); }
@Override public int capacity() { return capacity; }
@Override public List<K> keysLruFirst() {
throw new UnsupportedOperationException("Caffeine does not expose recency order");
}
}
@@ -0,0 +1,127 @@
package com.ankurm.interviewlab.lrucache;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
/**
* Implementation 2: what an interviewer means by "do it without LinkedHashMap".
*
* <p>A {@link HashMap} gives O(1) key to node. A doubly linked list gives O(1) "move this node to
* the front" and "drop the last node", because every node knows both neighbours. Two sentinel
* nodes ({@code head} and {@code tail}) mean no operation ever has to ask "is there a previous
* node?", so there are no null checks and no special cases for an empty or one-element list.
*
* <pre>
* head(sentinel) <-> MRU <-> ... <-> LRU <-> tail(sentinel)
* </pre>
*
* <p>NOT thread-safe by itself. The thread-safe variants in this package wrap it.
*/
public class HashMapLruCache<K, V> implements LruCache<K, V> {
static final class Node<K, V> {
K key;
V value;
Node<K, V> prev, next;
Node(K key, V value) { this.key = key; this.value = value; }
}
private final int capacity;
private final Map<K, Node<K, V>> index;
private final Node<K, V> head = new Node<>(null, null);
private final Node<K, V> tail = new Node<>(null, null);
/** Counts every pointer assignment made on a node. Lets a test prove the cost per operation. */
long pointerWrites;
public HashMapLruCache(int capacity) {
if (capacity <= 0) throw new IllegalArgumentException("capacity must be > 0: " + capacity);
this.capacity = capacity;
this.index = new HashMap<>(Math.max(16, (int) (capacity / 0.75f) + 1));
head.next = tail;
tail.prev = head;
}
@Override
public V get(K key) {
Objects.requireNonNull(key);
Node<K, V> n = index.get(key); // O(1) expected
if (n == null) return null;
unlink(n); // O(1): 2 pointer writes
linkAfterHead(n); // O(1): 4 pointer writes
return n.value;
}
@Override
public void put(K key, V value) {
Objects.requireNonNull(key);
Objects.requireNonNull(value);
Node<K, V> n = index.get(key);
if (n != null) { // existing key: replace value, make it MRU
n.value = value;
unlink(n);
linkAfterHead(n);
return;
}
if (index.size() == capacity) { // full: evict the node just before the tail sentinel
Node<K, V> lru = tail.prev;
unlink(lru);
index.remove(lru.key); // the node must remember its key, or this is impossible
}
n = new Node<>(key, value);
index.put(key, n);
linkAfterHead(n);
}
private void unlink(Node<K, V> n) {
n.prev.next = n.next;
n.next.prev = n.prev;
pointerWrites += 2;
}
private void linkAfterHead(Node<K, V> n) {
n.next = head.next;
n.prev = head;
head.next.prev = n;
head.next = n;
pointerWrites += 4;
}
@Override
public int size() { return index.size(); }
@Override
public int capacity() { return capacity; }
@Override
public List<K> keysLruFirst() {
List<K> out = new ArrayList<>(index.size());
for (Node<K, V> n = tail.prev; n != head; n = n.prev) out.add(n.key);
return out;
}
/**
* Structural self-check used by the stress tests: walks the list both ways and compares it to
* the hash index. Throws {@link IllegalStateException} naming the first broken invariant.
*/
public void checkInvariants() {
if (head.prev != null || tail.next != null) throw new IllegalStateException("sentinel has outer link");
int forward = 0;
Node<K, V> prev = head;
for (Node<K, V> n = head.next; n != tail; n = n.next) {
if (n == null) throw new IllegalStateException("forward walk hit null: list is cut");
if (n.prev != prev) throw new IllegalStateException("prev/next disagree at key " + n.key);
if (index.get(n.key) != n) throw new IllegalStateException("list node not in index: " + n.key);
prev = n;
if (++forward > capacity) throw new IllegalStateException("list longer than capacity (or cyclic)");
}
if (tail.prev != prev) throw new IllegalStateException("tail.prev is not the last forward node");
if (forward != index.size()) {
throw new IllegalStateException("list length " + forward + " != index size " + index.size());
}
if (forward > capacity) throw new IllegalStateException("over capacity: " + forward);
}
}
@@ -0,0 +1,69 @@
package com.ankurm.interviewlab.lrucache;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
/**
* Implementation 1: the ten-line answer. {@link LinkedHashMap} with {@code accessOrder = true}
* keeps entries in access order; {@code removeEldestEntry} is the hook it calls after every
* insertion, and returning {@code true} evicts the eldest (= least recently used) entry.
*
* <p>NOT thread-safe. See {@link SynchronizedLruCache} and friends.
* Explained in the article under "Implementation 1".
*/
public final class LinkedHashMapLruCache<K, V> implements LruCache<K, V> {
private final int capacity;
private final Lru<K, V> map;
public LinkedHashMapLruCache(int capacity) {
if (capacity <= 0) throw new IllegalArgumentException("capacity must be > 0: " + capacity);
this.capacity = capacity;
this.map = new Lru<>(capacity);
}
/** The classic interview class, shown on its own so the article can quote it. */
static final class Lru<K, V> extends LinkedHashMap<K, V> {
private final int capacity;
Lru(int capacity) {
// 3rd argument true = access order. Load factor 1.0f + capacity+1 slots: the map
// never needs to resize, because removeEldestEntry trims it back to `capacity`.
super(capacity + 1, 1.0f, true);
this.capacity = capacity;
}
@Override
protected boolean removeEldestEntry(Map.Entry<K, V> eldest) {
return size() > capacity;
}
}
@Override
public V get(K key) {
Objects.requireNonNull(key);
return map.get(key); // in access-order mode this relinks the entry to the tail
}
@Override
public void put(K key, V value) {
Objects.requireNonNull(key);
Objects.requireNonNull(value);
map.put(key, value);
}
@Override
public int size() { return map.size(); }
@Override
public int capacity() { return capacity; }
@Override
public List<K> keysLruFirst() { return new ArrayList<>(map.keySet()); }
/** Exposed for the "get() is a structural modification" demo. */
Map<K, V> rawMap() { return map; }
}
@@ -0,0 +1,30 @@
package com.ankurm.interviewlab.lrucache;
import java.util.List;
/**
* The contract every implementation in this module honours.
*
* <ul>
* <li>Fixed capacity, set at construction. Inserting a new key into a full cache evicts the
* <em>least recently used</em> entry.</li>
* <li>"Used" means {@code get} that hits, or {@code put} (new key or existing key).</li>
* <li>Null keys and null values are rejected with {@link NullPointerException}, so
* {@code get(k) == null} unambiguously means "absent".</li>
* </ul>
*/
public interface LruCache<K, V> {
/** Returns the value, or {@code null} if absent. A hit makes the key most recently used. */
V get(K key);
/** Inserts or replaces; makes the key most recently used; evicts the LRU entry if over capacity. */
void put(K key, V value);
int size();
int capacity();
/** Snapshot of the keys, least recently used first. Does NOT count as a use. For tests and demos. */
List<K> keysLruFirst();
}
@@ -0,0 +1,38 @@
package com.ankurm.interviewlab.lrucache;
import java.util.List;
import java.util.concurrent.locks.ReentrantLock;
/**
* Thread-safe variant B: the same single critical section as {@link SynchronizedLruCache}, spelled
* with {@link ReentrantLock}. It buys {@code tryLock}, timeouts and fairness, not parallelism:
* there is still exactly one lock, and every operation takes it.
*/
public final class ReentrantLockLruCache<K, V> implements LruCache<K, V> {
private final HashMapLruCache<K, V> delegate;
private final ReentrantLock lock = new ReentrantLock();
public ReentrantLockLruCache(int capacity) { this.delegate = new HashMapLruCache<>(capacity); }
@Override public V get(K key) {
lock.lock();
try { return delegate.get(key); } finally { lock.unlock(); }
}
@Override public void put(K key, V value) {
lock.lock();
try { delegate.put(key, value); } finally { lock.unlock(); }
}
@Override public int size() {
lock.lock();
try { return delegate.size(); } finally { lock.unlock(); }
}
@Override public int capacity() { return delegate.capacity(); }
@Override public List<K> keysLruFirst() {
lock.lock();
try { return delegate.keysLruFirst(); } finally { lock.unlock(); }
}
public void checkInvariants() {
lock.lock();
try { delegate.checkInvariants(); } finally { lock.unlock(); }
}
}
@@ -0,0 +1,71 @@
package com.ankurm.interviewlab.lrucache;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
/**
* Thread-safe variant C: lock striping. The key space is split by hash into {@code stripes}
* independent {@link SynchronizedLruCache} segments, each with its own lock and its own LRU list.
* Threads touching different segments do not contend.
*
* <p>The price is exactness: the eviction order is LRU <em>within a segment</em>, not globally.
* The globally oldest key can survive while a younger key in a full segment is evicted. Total
* capacity is {@code stripes * (requested / stripes)}, rounded down, at least one per stripe.
*/
public final class StripedLruCache<K, V> implements LruCache<K, V> {
/**
* How a key picks its segment. LOW_BITS is the obvious first attempt and a performance bug: it
* uses the same low bits of the hash that each segment's inner {@code HashMap} uses to pick a
* bucket, so every key in one segment lands in the same few buckets. MIXED multiplies by the
* 32-bit golden-ratio constant and takes high bits, which are independent of the low bits.
*/
public enum Selector {
LOW_BITS { @Override int index(int hash, int stripes) { return Math.floorMod(hash ^ (hash >>> 16), stripes); } },
MIXED { @Override int index(int hash, int stripes) { return Math.floorMod((hash * 0x9E3779B9) >>> 16, stripes); } };
abstract int index(int hash, int stripes);
/** Public for the bucket-distribution test. */
public int select(int hash, int stripes) { return index(hash, stripes); }
}
private final SynchronizedLruCache<K, V>[] segments;
private final int capacity;
private final Selector selector;
public StripedLruCache(int capacity, int stripes) { this(capacity, stripes, Selector.MIXED); }
@SuppressWarnings("unchecked")
public StripedLruCache(int capacity, int stripes, Selector selector) {
this.selector = selector;
if (capacity <= 0 || stripes <= 0) throw new IllegalArgumentException("capacity and stripes must be > 0");
int perStripe = Math.max(1, capacity / stripes);
this.segments = new SynchronizedLruCache[stripes];
for (int i = 0; i < stripes; i++) segments[i] = new SynchronizedLruCache<>(perStripe);
this.capacity = perStripe * stripes;
}
private SynchronizedLruCache<K, V> segmentFor(K key) {
return segments[selector.index(Objects.requireNonNull(key).hashCode(), segments.length)];
}
@Override public V get(K key) { return segmentFor(key).get(key); }
@Override public void put(K key, V value) { segmentFor(key).put(key, value); }
@Override public int size() {
int n = 0;
for (var s : segments) n += s.size(); // not an atomic snapshot across segments
return n;
}
@Override public int capacity() { return capacity; }
/** Concatenation of per-segment orders: NOT a global recency order. */
@Override public List<K> keysLruFirst() {
List<K> all = new ArrayList<>();
for (var s : segments) all.addAll(s.keysLruFirst());
return all;
}
public void checkInvariants() { for (var s : segments) s.checkInvariants(); }
}
@@ -0,0 +1,20 @@
package com.ankurm.interviewlab.lrucache;
import java.util.List;
/**
* Thread-safe variant A: one coarse monitor. {@code get} MUTATES the recency list, so every
* method, reads included, needs exclusive access. Simplest correct answer.
*/
public final class SynchronizedLruCache<K, V> implements LruCache<K, V> {
private final HashMapLruCache<K, V> delegate;
public SynchronizedLruCache(int capacity) { this.delegate = new HashMapLruCache<>(capacity); }
@Override public synchronized V get(K key) { return delegate.get(key); }
@Override public synchronized void put(K key, V value) { delegate.put(key, value); }
@Override public synchronized int size() { return delegate.size(); }
@Override public int capacity() { return delegate.capacity(); }
@Override public synchronized List<K> keysLruFirst() { return delegate.keysLruFirst(); }
public synchronized void checkInvariants() { delegate.checkInvariants(); }
}
@@ -0,0 +1,69 @@
package com.ankurm.interviewlab.lrucache.bench;
import com.ankurm.interviewlab.lrucache.*;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.concurrent.ThreadLocalRandom;
import java.util.concurrent.TimeUnit;
import org.openjdk.jmh.annotations.*;
/**
* The cache-aside access pattern: get; on a miss, put. Keys are uniform over 2x the capacity, so
* roughly half the lookups hit. The single-threaded implementations must be run with -t 1.
*
* Run: scripts/run-all.sh (short forks, INDICATIVE numbers on a shared 2-vCPU sandbox).
*/
@BenchmarkMode(Mode.Throughput)
@OutputTimeUnit(TimeUnit.MICROSECONDS)
@State(Scope.Benchmark)
public class LruBenchmark {
static final int CAPACITY = 1024;
static final int KEY_RANGE = CAPACITY * 2;
@Param({"linkedhashmap-unsafe", "dll-unsafe", "synchronizedMap(LinkedHashMap)", "synchronized", "reentrantlock", "striped16", "striped16-lowbits", "caffeine"})
public String impl;
private LruCache<Integer, Integer> cache;
@Setup(Level.Trial)
public void setUp() {
cache = switch (impl) {
case "linkedhashmap-unsafe" -> new LinkedHashMapLruCache<>(CAPACITY);
case "dll-unsafe" -> new HashMapLruCache<>(CAPACITY);
case "synchronizedMap(LinkedHashMap)" -> new SyncMapAdapter(CAPACITY);
case "synchronized" -> new SynchronizedLruCache<>(CAPACITY);
case "reentrantlock" -> new ReentrantLockLruCache<>(CAPACITY);
case "striped16" -> new StripedLruCache<>(CAPACITY, 16);
case "striped16-lowbits" -> new StripedLruCache<>(CAPACITY, 16, StripedLruCache.Selector.LOW_BITS);
case "caffeine" -> new CaffeineLru<>(CAPACITY);
default -> throw new IllegalArgumentException(impl);
};
for (int i = 0; i < CAPACITY; i++) cache.put(i, i); // warm: start full
}
@Benchmark
public Integer lookupThenFillOnMiss() {
int k = ThreadLocalRandom.current().nextInt(KEY_RANGE);
Integer v = cache.get(k);
if (v == null) { v = k; cache.put(k, v); }
return v;
}
/** Collections.synchronizedMap around an access-order LinkedHashMap: the "free" thread-safe LRU. */
static final class SyncMapAdapter implements LruCache<Integer, Integer> {
private final Map<Integer, Integer> m;
private final int capacity;
SyncMapAdapter(int capacity) {
this.capacity = capacity;
this.m = Collections.synchronizedMap(new LinkedHashMap<>(capacity + 1, 1.0f, true) {
@Override protected boolean removeEldestEntry(Map.Entry<Integer, Integer> e) { return size() > CAPACITY; }
});
}
public Integer get(Integer k) { return m.get(k); }
public void put(Integer k, Integer v) { m.put(k, v); }
public int size() { return m.size(); }
public int capacity() { return capacity; }
public java.util.List<Integer> keysLruFirst() { throw new UnsupportedOperationException(); }
}
}