Inside Guava Cache: Segments, Locks, LRU and Why It Lags Behind Caffeine

Guava Cache Architecture Overview

Guava Cache uses a segmented design where the cache is divided into multiple Segment objects, each protected by a ReentrantLock. Each segment stores entries in an AtomicReferenceArray of buckets, with entries linked via a singly‑linked list using a final next field. The cache maintains three LRU‑based queues ( accessQueue, writeQueue, recencyQueue) to track access order, write order and recent reads.

Key Data Structures

Segment

: holds the bucket array, lock, counters, and queues. AtomicReferenceArray<ReferenceEntry<K,V>>: the bucket table. ReferenceEntry implementations ( StrongEntry, StrongAccessWriteEntry) store key, hash, value reference and timestamps.

Queues implement LRU eviction based on access/write timestamps.

Put Operation

The put method hashes the key, routes to the appropriate segment via segmentFor, locks the segment, performs pre‑write cleanup, expands the table if needed, and either updates an existing entry or inserts a new one using head‑insertion. It records writes, updates the LRU queues, and triggers eviction when the segment exceeds its weight limit.

public V put(K key, V value) {
    checkNotNull(key);
    checkNotNull(value);
    int hash = hash(key);
    return segmentFor(hash).put(key, hash, value, false);
}

V Segment.put(K key, int hash, V value, boolean onlyIfAbsent) {
    lock();
    try {
        long now = map.ticker.read();
        preWriteCleanup(now);
        // expand if needed, locate bucket, insert or replace entry
        // update queues and possibly evict
    } finally {
        unlock();
        postWriteCleanup();
    }
}

Get Operation

The get method also routes to a segment but reads without acquiring the segment lock. It checks for expiration, records a read in recencyQueue, and returns the value if present. If the entry is missing or loading, it creates a LoadingValueReference, loads the value synchronously, and stores it.

public V get(K key) throws ExecutionException {
    int hash = hash(checkNotNull(key));
    return segmentFor(hash).get(key, hash, defaultLoader);
}

V Segment.get(K key, int hash, CacheLoader<? super K, V> loader) {
    // try fast path without lock, if miss load synchronously under lock
}

Lifecycle Management Methods

preWriteCleanup

: runs under lock, drains reference queues, expires entries, and resets readCount. expireEntries: removes entries whose access or write timestamps exceed configured expiration. expand: doubles the bucket array size, rehashes entries, and copies or deep‑copies nodes. evictEntries: uses accessQueue to evict least‑recently used entries when weight limits are exceeded. postWriteCleanup: processes pending removal notifications.

Comparison with Caffeine

Guava’s segmented lock design mirrors the pre‑JDK‑8 ConcurrentHashMap and incurs higher contention than Caffeine, which builds on the modern ConcurrentHashMap and employs CAS, lightweight synchronization, and a TinyLFU eviction policy. Caffeine also provides a time‑wheel for expiration and avoids cache‑line false sharing, offering superior performance for high‑concurrency workloads.

When to Choose Guava

For applications with modest concurrency requirements or where adding an extra dependency is undesirable, Guava Cache remains a viable option because it is already bundled with many projects.