# facebook/cachelib architecture

> Architecture diagram of the GitHub repository facebook/cachelib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebook/cachelib
- Repository: https://github.com/facebook/cachelib

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Tools Layer
    subgraph "Developer Tools" 
        direction TB
        GD["getdeps.py / fbcode_builder"]:::tools
        CMakeScripts["CMake Scripts"]:::tools
    end

    %% CacheLib Library
    subgraph "CacheLib Library"
        direction TB

        %% Core Utilities
        subgraph "Core Utilities" 
            direction TB
            CU["common (sync, hash, threading)"]:::core
        end

        %% Data Types
        DT["datatype (buffers, maps, views)"]:::core

        %% Cache APIs
        subgraph "Cache APIs"
            direction TB
            Allocator["allocator (DRAM slab, LRU, TinyLFU)"]:::backend
            Compact["compact_cache (fixed-size LRU)"]:::backend
            ObjectCache["object_cache (API + persistence)"]:::backend
        end

        %% Storage Engines & Optional Modules
        subgraph "Storage Engines & Modules"
            direction TB
            Navy["navy (SSD engine, I/O scheduler)"]:::backend
            SHM["shm (POSIX/SysV SHM)"]:::core
            Persistence["persistence (Thrift snapshots)"]:::core
            RustBinding["rust (C ABI shim)"]:::core
        end
    end

    %% Clients & Tools
    subgraph "Clients & Tools"
        direction TB
        Bench["cachebench (benchmark tool)"]:::tools
        Examples["examples (sample clients)"]:::tools
        Website["website (Docusaurus docs)"]:::tools
    end

    %% External Dependencies
    subgraph "External Libraries & Services"
        direction TB
        Boost["Boost"]:::external
        Folly["Folly"]:::external
        Thrift["Thrift"]:::external
        GTest["GTest"]:::external
        NVMe["NVMe Driver"]:::external
    end

    %% Dependencies / Flows
    GD -->|invokes| CMakeScripts
    CMakeScripts -->|builds| CU
    CMakeScripts -->|builds| DT
    CMakeScripts -->|builds| Allocator
    CMakeScripts -->|builds| Compact
    CMakeScripts -->|builds| ObjectCache
    CMakeScripts -->|builds| Navy
    CMakeScripts -->|builds| SHM
    CMakeScripts -->|builds| Persistence
    CMakeScripts -->|builds| RustBinding
    CMakeScripts -->|builds| Bench

    CU -->|used by| Allocator
    CU -->|used by| Navy
    CU -->|used by| Bench

    DT -->|used by| Allocator
    DT -->|used by| Navy
    DT -->|used by| Bench

    Allocator -->|interface| Compact
    Allocator -->|interface| ObjectCache

    SHM -->|enables| Navy
    Persistence -->|used by| ObjectCache
    Persistence -->|used by| Navy

    Navy -->|provides| ObjectCache
    Navy -->|schedules I/O| NVMe

    Bench -->|calls| Allocator
    Bench -->|calls| Navy
    Bench -->|uses| CU
    Examples -->|link against| Allocator
    Examples -->|link against| Navy

    Website -->|documents| CU
    Website -->|documents| Allocator
    Website -->|documents| Navy
    Website -->|documents| ObjectCache

    %% External links
    Allocator -->|depends| Boost
    Allocator -->|depends| Folly
    CU -->|depends| Folly
    ObjectCache -->|serializes| Thrift
    Persistence -->|serializes| Thrift
    Bench -->|tests with| GTest

    %% Click events
    click GD "https://github.com/facebook/cachelib/tree/main/build/fbcode_builder/"
    click CMakeScripts "https://github.com/facebook/cachelib/tree/main/cachelib/cmake/"
    click CMakeScripts "https://github.com/facebook/cachelib/tree/main/build/fbcode_builder/CMake/"
    click CU "https://github.com/facebook/cachelib/tree/main/cachelib/common/"
    click Allocator "https://github.com/facebook/cachelib/tree/main/cachelib/allocator/"
    click Compact "https://github.com/facebook/cachelib/tree/main/cachelib/compact_cache/"
    click DT "https://github.com/facebook/cachelib/tree/main/cachelib/datatype/"
    click SHM "https://github.com/facebook/cachelib/tree/main/cachelib/shm/"
    click Navy "https://github.com/facebook/cachelib/tree/main/cachelib/navy/"
    click ObjectCache "https://github.com/facebook/cachelib/tree/main/cachelib/object_cache/"
    click Persistence "https://github.com/facebook/cachelib/tree/main/cachelib/persistence/"
    click RustBinding "https://github.com/facebook/cachelib/tree/main/cachelib/rust/"
    click Bench "https://github.com/facebook/cachelib/tree/main/cachelib/cachebench/"
    click Examples "https://github.com/facebook/cachelib/tree/main/examples/"
    click Website "https://github.com/facebook/cachelib/tree/main/website/"

    %% Styles
    classDef tools fill:#9f6,stroke:#393,stroke-width:1px
    classDef core fill:#6cf,stroke:#069,stroke-width:1px
    classDef backend fill:#f96,stroke:#933,stroke-width:1px
    classDef external fill:#ddd,stroke:#999,stroke-width:1px,stroke-dasharray: 2 2
```
