How landry5/caffeine works
Project type and purpose
• This is a Java-based, multi-module library (“Caffeine”) providing a high-performance in-memory cache.
• Modules include:
– core cache engine (“caffeine”)
– adapters (“guava” and “jcache”)
– a trace-driven simulator (“simulator”)
– example clients under “examples/…”
• Build and CI/CD infrastructure is defined via Gradle scripts, custom plugins, and GitHub Actions.
File structure
• Top-level: a root Gradle project (settings.gradle.kts)
• Submodules: caffeine/, guava/, jcache/, simulator/, plus examples/ and gradle/plugins/
• Build scripts: build.gradle.kts at root, per-module builds, shared versioning in gradle/libs.versions.toml
• CI/CD: GitHub workflows (.github/workflows/*.yml), custom Gradle plugins (gradle/plugins), shell scripts (.github/scripts)
README highlights
• Core features: loading cache, size-based eviction, time-based expiration, async refresh, reference eviction, listeners, write-through, stats
• Extensions: JSR-107 (JCache), Guava compatibility, simulator
• Integration targets: Spring, Micronaut, Quarkus, Kafka, etc.
Main components
a. Client application(s): calls into the caching API
b. Caffeine core module:
– CacheBuilder → LocalCacheFactory → LocalCache
– Eviction mechanisms (FrequencySketch, Pacer, TimerWheel)
– Expiration (Ticker, Expiry policy)
– Concurrency (MpscGrowableArrayQueue, StripedBuffer)
– Statistics (StatsCounter implementations)
c. Extension modules:
– Guava adapter wraps core for Guava-style API
– JSR-107 adapter implements javax.cache.spi.CachingProvider on top of core
d. Simulator module:
– TraceReader(s) ingest external traces
– Admission policies (TinyLFU, CountMin, etc.) reuse core eviction logic
– Policy components register via a registry and produce Reports
e. Build infrastructure:
– Gradle root + plugins, shared configuration
– GitHub Actions CI pipeline
– Code generation (javaPoet in caffeine/src/javaPoet)
Relationships and interactions
• Client → Caffeine API → Core module
• Core module provides pluggable eviction/expiration/statistics internals
• Extensions depend on core and present alternate API layers
• Simulator depends on core eviction/expiry/policy implementations to evaluate performance
• Examples depend on core and extensions, demonstrating usage
• Gradle plugins apply across modules to standardize build/test quality
• CI/CD pipelines invoke Gradle tasks for build, test, benchmarks, security scans
Architectural patterns and design principles
• Modular multi-project structure (separation of core, adapters, simulation, examples)
• Pluggable components via factory and registry patterns (NodeFactory, PolicyRegistry)
• Code-generation at build time (javaPoet) for local cache implementations
• Single responsibility within modules: core engine vs API adapters vs simulator
• Extensive testing and benchmarking modules (jcstress, jmh, simulator, tests under each module)
Technologies, frameworks, and libraries
• Java 11+ (uses module-info.java)
• Gradle Kotlin DSL for builds and custom plugins
• GitHub Actions, Dependabot, Qodana, Snyk for CI/quality/security
• JMH and JCStress for benchmarks and concurrency stress tests
• javaPoet for code generation of cache variants