Caffeine — High-Performance Java Caching Library

Introduction

Caffeine is a high-performance, near-optimal caching library for Java. Inspired by Guava Cache but redesigned from the ground up, it uses the Window TinyLfu eviction policy to achieve hit rates close to the theoretical optimum while maintaining concurrent read/write performance.

What Caffeine Does

• Provides an in-memory cache with size-based, time-based, and reference-based eviction
• Implements the Window TinyLfu algorithm for near-optimal cache hit rates
• Supports automatic loading via CacheLoader or manual population
• Offers both synchronous (Cache/LoadingCache) and asynchronous (AsyncCache/AsyncLoadingCache) APIs
• Records cache statistics (hit rate, eviction count, load time) for monitoring and tuning

Architecture Overview

Caffeine uses a concurrent hash table as its backing store with lock-free reads. Write operations are buffered and replayed asynchronously to maintain the eviction policy metadata. The Window TinyLfu policy combines a small admission window (LRU) with a main space (segmented LRU), using a frequency sketch (Count-Min Sketch) to estimate access frequency and decide whether new entries should be admitted.

Self-Hosting & Configuration

• Add via Gradle: implementation("com.github.ben-manes.caffeine:caffeine:3.2.0")
• Set maximumSize or maximumWeight to control cache capacity
• Configure expireAfterWrite, expireAfterAccess, or refreshAfterWrite for time-based policies
• Enable recordStats() and export metrics to Micrometer or Prometheus for observability
• Use Caffeine as the cache provider for Spring Cache or Hibernate second-level cache

Key Features

• Window TinyLfu eviction policy delivers near-optimal hit rates across diverse workloads
• Lock-free concurrent reads with amortized O(1) write operations
• Async loading support for non-blocking cache population
• Configurable expiration and refresh policies with per-entry variable expiration via Expiry
• Seamless integration with Spring Cache, Hibernate, and Micronaut via adapters

Comparison with Similar Tools

• Guava Cache — predecessor with a similar API but uses LRU eviction and has lower hit rates on most workloads
• Ehcache — supports off-heap and disk tiers for larger data sets; heavier configuration overhead
• Redis/Valkey — distributed cache for multi-node setups; Caffeine is local JVM cache with lower latency
• Hazelcast — distributed in-memory data grid; overkill when a local cache suffices

FAQ

Q: How does Caffeine compare to Guava Cache in hit rates? A: Caffeine consistently achieves higher hit rates due to the Window TinyLfu policy, which considers both frequency and recency.

Q: Can I use Caffeine with Spring Boot? A: Yes. Spring Boot auto-configures Caffeine as a cache provider when it is on the classpath and spring.cache.type=caffeine is set.

Q: Does Caffeine support distributed caching? A: No. Caffeine is a local in-memory cache. For distributed caching, combine it with a remote cache as an L1/L2 setup.

Q: Is Caffeine thread-safe? A: Yes. All operations are thread-safe without external synchronization.

Sources

• https://github.com/ben-manes/caffeine
• https://github.com/ben-manes/caffeine/wiki