Skip to content

README.md

Latest commit

 

History

History
233 lines (172 loc) · 5.67 KB

README.md

File metadata and controls

233 lines (172 loc) · 5.67 KB

🚀 C++ Systems Playground

A hands-on C++ monorepo designed to practice systems programming fundamentals, including:

  • custom memory allocation
  • in-memory data structures
  • hash tables (chaining + open addressing)
  • caching & eviction
  • RAII + smart pointers
  • lock-free concurrency
  • thread pools & work stealing
  • modular CMake builds
  • logging
  • unit testing

This repository contains multiple realistic projects that build on each other — progressing from memory allocators → hash maps → KV stores → caching → smart pointers → concurrency.

📦 Modules Overview

Module Description
common/ Shared utilities (logging)
memory_pool/ Fixed-block allocator for efficient small allocations
hash_map/ Custom separate-chaining HashMap (replaces std::unordered_map)
kv_store_chaining/ KV store using chaining + memory_pool
kv_store_linear/ KV store using open addressing + fixed-inline buffers (cache-friendly)
lru_cache/ Modern LRU cache using hash_map + std::list
in_memory_redis/ Redis-style store with TTL, prefix lookup, background sweeper
smart_pointers/ Custom RAII pointers (UniquePtr, SharedPtr, WeakPtr)
lock_free_queue/ MPMC lock-free queue using atomic CAS (Michael–Scott style)
thread_pool/ Work-stealing thread pool with per-thread task queues & futures

Each module:

  • is standalone
  • exports a library target
  • has a demo executable
  • has unit tests
  • avoids dependencies except STL / gtest

📋 Module Dependency Graph

common (logging utilities)
  ├─ memory_pool (allocators)
  │  └─ kv_store_chaining
  │     └─ (application layer)
  │
  ├─ hash_map (chaining-based)
  │  ├─ kv_store_chaining
  │  └─ lru_cache
  │     └─ in_memory_redis
  │
  ├─ kv_store_linear (independent)
  ├─ smart_pointers (RAII utilities)
  ├─ lock_free_queue (concurrency)
  └─ thread_pool (concurrency)

Dependency Rules:

  • common ← base layer (no dependencies)
  • Foundation layer ← common only
  • Application layer ← Foundation + others as needed
  • Concurrency (lock_free_queue, thread_pool) ← common only (no cross-dependencies)

🧩 Monorepo Structure

cpp-systems-playground/
│
├── common/
├── memory_pool/
├── hash_map/
│
├── kv_store_chaining/
├── kv_store_linear/
│
├── lru_cache/
├── in_memory_redis/
│
├── smart_pointers/
├── lock_free_queue/
├── thread_pool/
│
└── build/

KV Store Differences

Module Collision Handling Allocation Value Storage Strength
chaining separate chaining pool dynamic flexible & simple
linear probing open addressing contiguous fixed inline fast & cache-efficient

Concurrency Modules

Module Focus / Concept
lock_free_queue atomic CAS, ABA avoidance, MPMC queues
thread_pool work stealing + futures + per-thread queues

⚙️ Build Instructions

Configure:

cmake -S . -B build

Build everything:

cmake --build build -j

Sample specific targets:

cmake --build build --target lock_free_queue_demo
cmake --build build --target thread_pool_demo
cmake --build build --target in_memory_redis_demo

🔥 Run Demos

./build/lock_free_queue/lock_free_queue_demo
./build/thread_pool/work_stealing_thread_pool_demo

Also available:

./build/hash_map/hash_map_demo
./build/lru_cache/lru_cache_demo
./build/smart_pointers/smart_pointers_demo

🧪 Unit Testing

Run all:

cd build
ctest --output-on-failure

Examples:

./build/lock_free_queue/lock_free_queue_tests
./build/thread_pool/thread_pool_tests
./build/kv_store_linear/kv_store_linear_tests

🌟 Learning Outcomes

By completing this repo, you’ll understand:

Data Structures

  • hash maps (chaining + open addressing)
  • memory pool allocators
  • KV stores
  • LRU caching

Concurrency

  • lock-free MPMC queues
  • thread pools & futures
  • work-stealing schedulers
  • condition variable wake/sleep
  • atomic CAS operations

Modern C++ Concepts

  • RAII + ownership models
  • templates + type traits
  • std::invoke_result_t
  • std::function, std::packaged_task
  • orphan avoidance & move semantics

🚧 Future Enhancements

Potential next modules:

  • robin-hood hashing
  • PMR-optimized structures
  • persistent backed Redis (WAL)
  • parallel sort / map-reduce
  • Lock-free stack
  • actor runtime on thread pool
  • benchmark suite

🤝 Contributing

Open to:

  • performance improvements
  • lock-free structures
  • thread pool extensions
  • bug reports & tests
  • benchmark additions
  • more allocator patterns

This is a playground — explore, break, optimize, and learn.

📄 License

MIT — free to use and modify.