From cac0b10074c815f4a890b2b03800e9b1f9483eb6 Mon Sep 17 00:00:00 2001
From: nircoe <nircoe@gmail.com>
Date: Tue, 12 Aug 2025 20:43:20 +0300
Subject: [PATCH] [Feature]: Introduce UNLIMITED_CACHE constant

---
 README.md                       | 17 ++++++++++++++++-
 docs/ARCHITECTURE.md            | 15 ++++++++++-----
 include/soundcoe/core/types.hpp |  3 +++
 3 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 10844aa..43863a7 100644
--- a/README.md
+++ b/README.md
@@ -136,7 +136,7 @@ soundcoe::initialize("./audio");  // relative to executable
 soundcoe::initialize(
     "./audio",        // Audio root directory (relative to executable)
     32,              // Max sources (default: 32)
-    64,              // Cache size MB (default: 64)
+    64,              // Cache size MB (default: 64, use soundcoe::UNLIMITED_CACHE for no limit)
     "sfx",           // Sound subdirectory inside each scene/general (default: "sfx")
     "music",         // Music subdirectory inside each scene/general (default: "music")
     LogLevel::INFO   // Log level (default: INFO)
@@ -146,6 +146,21 @@ soundcoe::initialize(
 soundcoe::shutdown();
 ```
 
+### Cache Management
+
+soundcoe automatically manages audio file caching for optimal performance:
+
+```cpp
+// Standard cache limits
+soundcoe::initialize("./audio", 32, 64);       // 64MB cache limit
+soundcoe::initialize("./audio", 32, 256);      // 256MB cache limit
+
+// Development/Testing: measure actual memory usage
+soundcoe::initialize("./audio", 32, soundcoe::UNLIMITED_CACHE);
+```
+
+**Development Tip**: Use `soundcoe::UNLIMITED_CACHE` during testing to measure your game's peak audio memory usage, then set an appropriate limit for your target platforms.
+
 ### Scene Management
 ```cpp
 // Load scene audio
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 5b86cbe..7562b8b 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -22,9 +22,10 @@ int main() {
     soundcoe::initialize(
         "./audio",    // Audio directory (relative to executable)
         64,           // Max simultaneous sources (good for action games)
-        128,          // Cache size MB (adjust based on your audio assets)
+        128,          // Cache size MB (adjust based on your audio assets, or soundcoe::UNLIMITED_CACHE)
         "sfx",        // Sound subdirectory inside each scene/general
-        "music"       // Music subdirectory inside each scene/general
+        "music",      // Music subdirectory inside each scene/general
+        LogLevel::INFO // Log level (default: INFO)
     );
     
     soundcoe::preloadScene("level1");
@@ -171,15 +172,18 @@ soundcoe::unloadScene("current_scene");     // Then unload current scene
 // Adjust cache size based on your game's scene complexity
 soundcoe::initialize("./audio", 32, 64);     // 64MB cache for simple scenes
 soundcoe::initialize("./audio", 64, 256);    // 256MB cache for complex scenes
+
+// Development/profiling: measure actual memory usage
+soundcoe::initialize("./audio", 32, soundcoe::UNLIMITED_CACHE);
 ```
 
 ### Source Pool Optimization
 
 ```cpp
 // Configure source pool based on your game - choose how many sources that you would like! remember it is the maximum concurrent amount.
-soundcoe::initialize("./audio", 16);         // 16 sources for games with less concurrent audio
-soundcoe::initialize("./audio", 32);         // 32 sources - default
-soundcoe::initialize("./audio", 64);         // 64 sources for game with more concurrent audio
+soundcoe::initialize("./audio", 16, 64);     // 16 sources for games with less concurrent audio
+soundcoe::initialize("./audio", 32, 64);     // 32 sources - default
+soundcoe::initialize("./audio", 64, 128);    // 64 sources for game with more concurrent audio
 ```
 
 ### Supported Audio Format
@@ -450,6 +454,7 @@ cmake -B build \
 ### Caching Strategy
 - **LRU Eviction**: Least recently used buffers removed first
 - **Size Limits**: Configurable maximum cache size in MB
+- **Unlimited Cache**: Use `soundcoe::UNLIMITED_CACHE` for development/profiling to measure peak memory usage
 - **Usage Tracking**: Statistical data for optimization decisions
 
 ## Audio Format Integration
diff --git a/include/soundcoe/core/types.hpp b/include/soundcoe/core/types.hpp
index 52455fa..188abdb 100644
--- a/include/soundcoe/core/types.hpp
+++ b/include/soundcoe/core/types.hpp
@@ -4,11 +4,14 @@
 #include <cmath>
 #include <string_view>
 #include <sstream>
+#include <limits>
 
 namespace soundcoe
 {
     using LogLevel = logcoe::LogLevel;
 
+    constexpr size_t UNLIMITED_CACHE = std::numeric_limits<size_t>::max();
+
     enum class SoundState
     {
         Initial,