How facebook/cachelib works
Project Type and Purpose
• CacheLib is an open-source C++ library (not a standalone service) that provides an in-process, high-performance, thread-safe caching engine.
• It includes modular pluggable cache back-ends (DRAM, hybrid, SSD via “Navy”), a persistence layer, a benchmark tool (CacheBench), language bindings (Rust), and examples & docs.
File‐Structure Analysis
Top‐level directories:
• build/fbcode_builder & getdeps.py – download/build dependencies & orchestrate CMake builds
• cachelib/ – core library subdivided into modules (allocator, common, compact_cache, datatype, navy, object_cache, persistence, shm, rust, cachebench)
• examples/ – sample CMake-based example clients
• contrib/ – scripts for packaging & environment setup
• website/ – documentation site (Docusaurus)
Patterns:
– Modular layered architecture: common utilities → core allocator → higher-level caches → optional backends (Navy, object_cache) → benchmarks & examples
– CMake/cmake scripts, getdeps.py orchestrate third-party deps (boost, folly, gflags, thrift, etc.)
README Insights
– Describes CacheLib’s goals, build & dependency workflow (getdeps.py + CMake), and CacheBench usage.
Main Components & Interactions
a. Developer Tools (build orchestration)
• getdeps.py / fbcode_builder → fetch/build 3rd-party deps → invokes CMake
• CMake scripts → build all modules + tests
b. Core Utilities (cachelib/common)
• Synchronization, hashing, serialization helpers, threading, stats
c. DRAM Cache Allocator (cachelib/allocator)
• Slab allocation, LRU/TinyLFU, Pool rebalancing, Memory Monitor
• Depends on common + datastruct (thrift objects)
d. Compact Cache (cachelib/compact_cache)
• Specialized fixed-size LRU buckets
• Built on allocator interfaces
e. Data Types (cachelib/datatype)
• Buffers, maps, views used by allocator & Navy
f. Shared-Memory Manager (cachelib/shm)
• POSIX/SysV SHM abstractions
• Allows cross-process caching
g. Hybrid/SSD Engine “Navy” (cachelib/navy)
• Device layer (NVMe), I/O scheduler, Driver, Engine abstraction
• Block-cache & BigHash back-ends, Admission policies, Serialization (thrift)
• Depends on common + datatype + shm
h. Object Cache (cachelib/object_cache)
• ObjectCache API wrapping allocator + persistence
i. Persistence (cachelib/persistence)
• PersistenceManager (thrift-based serialized snapshots)
• Used by object_cache & hybrid caches
j. Language Binding (cachelib/rust)
• Exposes C++ API to Rust via C ABI shim
k. Benchmark Tool (cachelib/cachebench)
• Main executable + runner/stressor modules
• Uses allocator, Navy, common, datatype to generate workloads & collect metrics
l. Examples & Website
• Example clients showing minimal CMake + code
• Docusaurus site for architecture/user guides
Architectural Patterns & Principles
– Layered, modular design: clear separation of utilities, core logic, back-ends, tools.
– Plug-in back-ends: allocator API abstracts DRAM vs SSD caching.
– Serialization via Thrift for persistence & interop.
– Shared-memory abstraction for cross-process usage.
– Build-time dependency management via getdeps + CMake.