Skip to content

Commit 8a59713

Browse files
docs: document memory leak testing in README
- Add comprehensive Testing section with Memory Leak Testing subsection - Document how to run tests with AddressSanitizer - Document Valgrind integration (make test-valgrind) - List all 10 test scenarios covered by test-memory-leaks.cpp - Include build commands, test execution instructions - Document environment variables and CI integration - Reference known issues (test-opt.cpp leak) Addresses GitHub comment from @stephencornwell requesting README update. Co-Authored-By: Stephen Cornwell <[email protected]>
1 parent d54e7d8 commit 8a59713

File tree

1 file changed

+75
-0
lines changed

1 file changed

+75
-0
lines changed

README.md

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -542,6 +542,81 @@ To learn more about model quantization, [read this documentation](tools/quantize
542542
- [Performance troubleshooting](docs/development/token_generation_performance_tips.md)
543543
- [GGML tips & tricks](https://github.com/ggml-org/llama.cpp/wiki/GGML-Tips-&-Tricks)
544544
545+
#### Testing
546+
547+
##### Memory Leak Testing
548+
549+
The repository includes comprehensive memory leak regression tests to ensure proper memory management across various lifecycle scenarios. These tests go beyond the existing AddressSanitizer (ASan) integration by providing dedicated leak detection test suites.
550+
551+
**Running with AddressSanitizer:**
552+
553+
The primary memory leak detection mechanism uses AddressSanitizer, which is configured as a build option:
554+
555+
```bash
556+
# Build with AddressSanitizer enabled
557+
cmake -B build -DLLAMA_SANITIZE_ADDRESS=ON -DCMAKE_BUILD_TYPE=Debug
558+
cmake --build build
559+
560+
# Run the memory leak regression tests
561+
cd build
562+
ctest -R test-memory-leaks --output-on-failure
563+
564+
# Or run directly
565+
./bin/test-memory-leaks
566+
```
567+
568+
Other available sanitizers:
569+
- `LLAMA_SANITIZE_THREAD=ON` - Detects data races (note: runs without OpenMP)
570+
- `LLAMA_SANITIZE_UNDEFINED=ON` - Detects undefined behavior
571+
572+
**Running with Valgrind:**
573+
574+
Optional Valgrind integration is available for additional leak checking:
575+
576+
```bash
577+
# Build the tests (Valgrind target is automatically configured if valgrind is installed)
578+
cmake -B build
579+
cmake --build build
580+
581+
# Run memory leak tests with Valgrind
582+
cd build
583+
make test-valgrind
584+
```
585+
586+
The Valgrind target runs with comprehensive leak detection flags:
587+
- `--leak-check=full` - Detailed leak information
588+
- `--show-leak-kinds=all` - Reports all leak types
589+
- `--track-origins=yes` - Tracks origin of uninitialized values
590+
591+
**Test Coverage:**
592+
593+
The `test-memory-leaks.cpp` suite includes 10 comprehensive tests covering:
594+
595+
1. **Backend initialization cycles** - Repeated `llama_backend_init()` / `llama_backend_free()` cycles
596+
2. **Model load/unload cycles** - Repeated model loading and cleanup (10 iterations)
597+
3. **Context lifecycle** - Context creation and destruction patterns (10 iterations)
598+
4. **Multiple contexts per model** - Creating multiple contexts from the same model (5 contexts)
599+
5. **Sampler lifecycle** - Sampler creation, chain operations, and cleanup
600+
6. **Batch operations** - Batch allocation and deallocation patterns
601+
7. **KV cache clearing** - Memory clearing operations on contexts
602+
8. **Threaded contexts** - Concurrent model usage with multiple threads
603+
9. **Model load cancellation** - Cleanup when canceling model loading mid-process
604+
10. **Error condition cleanup** - Proper cleanup when operations fail (e.g., invalid model path)
605+
606+
All tests follow proper cleanup order: sampler → context → model → backend.
607+
608+
**Environment Variables:**
609+
610+
- `LLAMACPP_TEST_MODELFILE` - Path to test model file (required for running tests)
611+
612+
**Continuous Integration:**
613+
614+
The GitHub Actions CI automatically runs all tests with all three sanitizers (ADDRESS, THREAD, UNDEFINED) on every pull request to catch memory issues before they reach production.
615+
616+
**Known Issues:**
617+
618+
- `test-opt.cpp` is currently disabled with `LLAMA_SANITIZE_ADDRESS` due to a known memory leak in `ggml_opt_alloc()` called within a loop (see `tests/test-opt.cpp:300`)
619+
545620
#### Seminal papers and background on the models
546621
547622
If your issue is with model generation quality, then please at least scan the following links and papers to understand the limitations of LLaMA models. This is especially important when choosing an appropriate model size and appreciating both the significant and subtle differences between LLaMA models and ChatGPT:

0 commit comments

Comments
 (0)