memviz 1.2.1

Embedded Low-Level Memory Visualization for C++

MemViz

MemViz is a teaching & visualization tool for C++ memory performance.
It helps students and developers understand:

• 📦 Memory layout (structs, padding, vtables)
• 💾 Cache behavior (L1/L2/L3 misses, read vs write)
• 🚀 Performance costs of poor data locality

MemViz is designed as a CLI tool + Python library.
It integrates with Valgrind/Cachegrind and shows results in a clear, color-coded summary.

---

✨ Features

• ✅ Run your C++ program under Valgrind/Cachegrind
• ✅ Parse cache statistics into a clean report
• ✅ Color-coded traffic light indicators (green/yellow/red)
• ✅ Read vs Write miss rates shown side-by-side
• ✅ Works with Docker fallback (for macOS/Apple Silicon)
• ✅ Great for teaching cache locality, struct packing, and memory efficiency

---

🔧 Installation

From PyPI:

pip install memviz

⸻

🚀 Quickstart

1. Compile your C++ program with debug info:

g++ -g -O2 ./examples/memTracker.cpp -o ./examples/memTracker

2. Run MemViz Cachegrind:

memviz cachegrind ./examples/memTracker

3. See results:

=======================  SUMMARY   =======================
INSTRUCTIONS MISS RATE: 
        1. L1 I-cache miss rate: 0.1% ✅
        2. Last-level instruction miss rate: 0.1% ✅

DATA MISS RATE: 
        1. L1 D-cache miss rate: 1.94% ✅
        2. Last-level D-cache miss rate: 1.21% 🟨

OVERALL LAST LEVEL MISS RATE: 66.56% 🔴

READ       vs    WRITE     
-------------------------
3.6%          1.95% 

📦 Docker Support

On macOS (especially ARM/M1/M2), Valgrind may not be available. MemViz automatically falls back to Docker if needed.

📚 Documentation

•	CLI Usage Guide
•	Valgrind Documentation
•	Background on Cache Locality

🛠 Development

Clone and install in editable mode:

git clone https://github.com/yourname/memviz.git
cd memviz
pip install -e .

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

⸻