# justpranavrs/tlru architecture

> Architecture diagram of the GitHub repository justpranavrs/tlru, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/justpranavrs/tlru
- Repository: https://github.com/justpranavrs/tlru

## Overview

1. **What this repository is**
   - `tlru` is a Go cache library, not an application.
   - The architecture is split into a **public facade in the module root** and a **lower-level `core` engine**. The root package exposes the user-facing cache types; `core` contains the actual storage and eviction algorithms.

2. **Public API layer**
   - The root files (`lru.go`, `slru.go`, `tlru.go`, `pool.go`, `tpool.go`) provide the constructors and option-based configuration for the exported cache types.
   - This layer is the main boundary for consumers: they choose between single-instance caches and pooled/sharded caches, and between plain, TTL, and segmented variants.

3. **Core cache engine**
   - `core/` holds the fundamental implementations: `core.LRU`, `core.TLRU`, `core.SLRU`, and `core.TSLRU`.
   - These are array-based, generic caches built for fixed capacity and zero runtime allocations. The README indicates they use int32 indices rather than heap-heavy linked nodes, which is the main performance design choice.

4. **Single-instance vs sharded architecture**
   - The library has two runtime shapes:
     - **Single cache instances** in `core/`, which preserve global eviction behavior.
     - **Pooled/sharded caches** in the root package, which route each key to one shard and scale under concurrency by avoiding a global lock.
   - Sharded caches trade perfect global LRU ordering for throughput and reduced contention.

5. **Time-to-live subsystem**
   - TTL behavior lives in `core.TLRU` / `core.TSLRU` and the root `tlru`/`tpool` wrappers.
   - TTL is **lazy**: expiration is checked on `Get` and `Peek`, not by a background cleanup goroutine.
   - The model supports both **absolute TTL** and **sliding TTL**. A clock abstraction in `clock/` lets the cache use a custom time source.

6. **Segmented cache subsystem**
   - `core.SLRU` and `core.TSLRU` implement segmented LRU using two internal regions: **probationary** and **protected**.
   - The promotion path reduces scan pollution and is intended to improve hit rate compared with plain LRU.
   - The root `slru.go` / `tpool.go` files expose the sharded versions of these caches.

7. **Sharding and key routing**
   - `mux/` is the sharding router. It maps a key to a shard index using selectable hash strategies.
   - The shipped hashers are `fnv`, `xxh`, and `maphash`, which allows the cache to support different key types and distribution characteristics.
   - This router is the key boundary between the public pooled cache and the underlying `core` instances.

8. **Synchronization model**
   - Concurrency is handled primarily at the shard/cache level rather than by a single global lock.
   - `core/` includes shared synchronization support in `sync.go`, while each `core` cache instance manages its own mutex-protected state.
   - This makes the sharded caches naturally scalable while keeping the single-cache implementation simple.

9. **Batch and hot-path optimizations**
   - `core.LRU` includes batch-oriented operations such as `GetMany` and `PutMany`, which are optimized to reduce lock contention.
   - The pooled wrappers do not expose the same batch semantics as prominently; the performance focus is on fast single-key operations through shard routing.

10. **Internal/test-only utilities**
   - `internal/testutil/` is isolated test scaffolding: deterministic data generation, random data, and shared test setup.
   - It does not participate in runtime architecture; it exists to support correctness tests and benchmarks across the cache variants.

11. **Repository structure and validation**
   - The `*_test.go` and `*_example_test.go` files are used to verify behavior and document usage patterns.
   - CI is defined in `.github/workflows/test.yml`, and linting is configured via `.golangci.yaml`.
   - The repo is therefore centered on a high-performance library core, with tests and benchmarks reinforcing the cache contracts and performance claims.

12. **Main data flow to diagram**
   - Consumer calls root constructor → root wrapper selects cache flavor/options → keys are optionally routed by `mux` to a shard → shard delegates to a `core` cache instance → `core` performs lookup/update/eviction using its internal array-based structure and optional TTL clock.

Main entry points: [`core/tlru.go`](https://github.com/justpranavrs/tlru/blob/main/core/tlru.go) (TLRU Core), [`mux/mux.go`](https://github.com/justpranavrs/tlru/blob/main/mux/mux.go) (Mux), [`core/lru.go`](https://github.com/justpranavrs/tlru/blob/main/core/lru.go) (LRU Core), [`core/slru.go`](https://github.com/justpranavrs/tlru/blob/main/core/slru.go) (SLRU Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_root_lru["LRU API<br/>facade<br/>[lru.go]"]
  node_root_slru["SLRU API<br/>facade<br/>[slru.go]"]
  node_root_tlru["TLRU API<br/>facade<br/>[tlru.go]"]
  node_root_pool["Pool API<br/>facade<br/>[pool.go]"]
  node_root_tpool["TPool API<br/>facade<br/>[tpool.go]"]
end

subgraph group_core["Core Engine"]
  node_core_lru["LRU Core<br/>cache engine<br/>[lru.go]"]
  node_core_slru["SLRU Core<br/>cache engine<br/>[slru.go]"]
  node_core_tlru["TLRU Core<br/>cache engine<br/>[tlru.go]"]
  node_core_sync["Sync<br/>runtime support<br/>[sync.go]"]
  node_core_types["Types<br/>runtime support<br/>[types.go]"]
end

subgraph group_routing["Sharding Router"]
  node_mux["Mux<br/>shard router<br/>[mux.go]"]
  node_mux_fnv["FNV<br/>hasher<br/>[fnv.go]"]
  node_mux_xxh["XXH<br/>hasher<br/>[xxh.go]"]
  node_mux_mh["MapHash<br/>hasher<br/>[mh.go]"]
end

subgraph group_time["Time"]
  node_clock["Clock<br/>time source<br/>[clock.go]"]
end

subgraph group_test["Test Utilities"]
  node_testutil["Test Util<br/>test scaffolding<br/>[setup.go]"]
end

node_consumer(("Consumer<br/>library user"))

node_consumer -->|"uses"| node_root_lru
node_consumer -->|"uses"| node_root_slru
node_consumer -->|"uses"| node_root_tlru
node_consumer -->|"uses"| node_root_pool
node_consumer -->|"uses"| node_root_tpool
node_root_lru -->|"wraps"| node_core_lru
node_root_slru -->|"wraps"| node_core_slru
node_root_tlru -->|"wraps"| node_core_tlru
node_root_pool -->|"routes"| node_mux
node_root_tpool -->|"routes"| node_mux
node_mux -->|"hashes"| node_mux_fnv
node_mux -->|"hashes"| node_mux_xxh
node_mux -->|"hashes"| node_mux_mh
node_root_pool -->|"shards"| node_core_lru
node_root_tpool -->|"shards"| node_core_tlru
node_core_lru -->|"locks"| node_core_sync
node_core_slru -->|"locks"| node_core_sync
node_core_tlru -->|"locks"| node_core_sync
node_core_tlru -->|"reads time"| node_clock
node_core_lru -->|"shares"| node_core_types
node_core_slru -->|"shares"| node_core_types
node_core_tlru -->|"shares"| node_core_types
node_testutil -.->|"supports tests"| node_core_lru
node_testutil -.->|"supports tests"| node_core_slru
node_testutil -.->|"supports tests"| node_core_tlru

click node_root_lru "https://github.com/justpranavrs/tlru/blob/main/lru.go"
click node_root_slru "https://github.com/justpranavrs/tlru/blob/main/slru.go"
click node_root_tlru "https://github.com/justpranavrs/tlru/blob/main/tlru.go"
click node_root_pool "https://github.com/justpranavrs/tlru/blob/main/pool.go"
click node_root_tpool "https://github.com/justpranavrs/tlru/blob/main/tpool.go"
click node_core_lru "https://github.com/justpranavrs/tlru/blob/main/core/lru.go"
click node_core_slru "https://github.com/justpranavrs/tlru/blob/main/core/slru.go"
click node_core_tlru "https://github.com/justpranavrs/tlru/blob/main/core/tlru.go"
click node_core_sync "https://github.com/justpranavrs/tlru/blob/main/core/sync.go"
click node_core_types "https://github.com/justpranavrs/tlru/blob/main/core/types.go"
click node_mux "https://github.com/justpranavrs/tlru/blob/main/mux/mux.go"
click node_mux_fnv "https://github.com/justpranavrs/tlru/blob/main/mux/fnv.go"
click node_mux_xxh "https://github.com/justpranavrs/tlru/blob/main/mux/xxh.go"
click node_mux_mh "https://github.com/justpranavrs/tlru/blob/main/mux/mh.go"
click node_clock "https://github.com/justpranavrs/tlru/blob/main/clock/clock.go"
click node_testutil "https://github.com/justpranavrs/tlru/blob/main/internal/testutil/setup.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_lru,node_root_slru,node_root_tlru,node_root_pool,node_root_tpool toneBlue
class node_core_lru,node_core_slru,node_core_tlru,node_core_sync,node_core_types toneAmber
class node_mux,node_mux_fnv,node_mux_xxh,node_mux_mh toneMint
class node_clock toneRose
class node_testutil toneIndigo
class node_consumer toneNeutral
```

## Components

### Public API

User-facing constructors and cache variants at the module root

- [LRU API](https://github.com/justpranavrs/tlru/blob/main/lru.go): facade · Single-instance LRU constructors and options · `lru.go`
- [SLRU API](https://github.com/justpranavrs/tlru/blob/main/slru.go): facade · Single-instance segmented LRU constructors and options · `slru.go`
- [TLRU API](https://github.com/justpranavrs/tlru/blob/main/tlru.go): facade · Single-instance TTL-aware cache constructors and options · `tlru.go`
- [Pool API](https://github.com/justpranavrs/tlru/blob/main/pool.go): facade · Sharded pooled cache constructors · `pool.go`
- [TPool API](https://github.com/justpranavrs/tlru/blob/main/tpool.go): facade · Sharded TTL-aware pooled cache constructors · `tpool.go`

### Core Engine

Fixed-capacity cache implementations and shared runtime support

- [LRU Core](https://github.com/justpranavrs/tlru/blob/main/core/lru.go): cache engine · Array-based fixed-capacity LRU implementation · `core/lru.go`
- [SLRU Core](https://github.com/justpranavrs/tlru/blob/main/core/slru.go): cache engine · Probationary/protected segmented LRU implementation · `core/slru.go`
- [TLRU Core](https://github.com/justpranavrs/tlru/blob/main/core/tlru.go): cache engine · TTL-aware LRU implementation with lazy expiration · `core/tlru.go`
- [Sync](https://github.com/justpranavrs/tlru/blob/main/core/sync.go): runtime support · Shared synchronization and locking support · `core/sync.go`
- [Types](https://github.com/justpranavrs/tlru/blob/main/core/types.go): runtime support · Shared core data structures and generic types · `core/types.go`

### Sharding Router

Key-to-shard routing and hash strategy selection

- [Mux](https://github.com/justpranavrs/tlru/blob/main/mux/mux.go): shard router · Routes keys to shards using selectable hashers · `mux/mux.go`
- [FNV](https://github.com/justpranavrs/tlru/blob/main/mux/fnv.go): hasher · Hash strategy for shard routing · `mux/fnv.go`
- [XXH](https://github.com/justpranavrs/tlru/blob/main/mux/xxh.go): hasher · Hash strategy for shard routing · `mux/xxh.go`
- [MapHash](https://github.com/justpranavrs/tlru/blob/main/mux/mh.go): hasher · Hash strategy for shard routing · `mux/mh.go`

### Time

Clock abstraction used by TTL-aware caches

- [Clock](https://github.com/justpranavrs/tlru/blob/main/clock/clock.go): time source · Abstract time source for TTL calculations · `clock/clock.go`

### Test Utilities

Shared scaffolding for tests and benchmarks

- [Test Util](https://github.com/justpranavrs/tlru/blob/main/internal/testutil/setup.go): test scaffolding · Shared deterministic data and setup helpers · `internal/testutil/setup.go`

### Other components

- **Consumer**: library user · External code using the cache library

## Connections

- Consumer → LRU API: uses · Consumers create single-instance LRU caches
- Consumer → SLRU API: uses · Consumers create single-instance segmented caches
- Consumer → TLRU API: uses · Consumers create TTL-aware caches
- Consumer → Pool API: uses · Consumers create sharded pooled caches
- Consumer → TPool API: uses · Consumers create sharded TTL-aware pooled caches
- LRU API → LRU Core: wraps · Facade delegates to the core LRU engine
- SLRU API → SLRU Core: wraps · Facade delegates to the core SLRU engine
- TLRU API → TLRU Core: wraps · Facade delegates to the TTL-aware core engine
- Pool API → Mux: routes · Sharded caches use mux to select a shard
- TPool API → Mux: routes · TTL sharded caches use mux to select a shard
- Mux → FNV: hashes · Supports FNV-based shard distribution
- Mux → XXH: hashes · Supports XXH-based shard distribution
- Mux → MapHash: hashes · Supports maphash-based shard distribution
- Pool API → LRU Core: shards · Each shard owns a core cache instance
- TPool API → TLRU Core: shards · Each shard owns a TTL-aware core cache instance
- LRU Core → Sync: locks · Core cache state is protected by internal synchronization
- SLRU Core → Sync: locks · Core cache state is protected by internal synchronization
- TLRU Core → Sync: locks · Core cache state is protected by internal synchronization
- TLRU Core → Clock: reads time · TTL expiry checks use the clock abstraction
- LRU Core → Types: shares · Core engines share generic types and internal structures
- SLRU Core → Types: shares · Core engines share generic types and internal structures
- TLRU Core → Types: shares · Core engines share generic types and internal structures
- Test Util → LRU Core: supports tests · Shared test scaffolding exercises core cache behavior
- Test Util → SLRU Core: supports tests · Shared test scaffolding exercises core cache behavior
- Test Util → TLRU Core: supports tests · Shared test scaffolding exercises core cache behavior