ENH: Add MemoryBudgetManager to simplnx core

Adds a unified cache budget manager to simplnx. Tracks allocations
registered by cache subsystems (ChunkCache, stride cache, etc.) and
evicts globally-oldest entries via callbacks when memory pressure
exceeds the configured budget. Singleton; thread-safe; the public
API matches the previous OocMemoryBudgetManager but lives in simplnx
core so non-OOC builds and visualization code can use it without
depending on the SimplnxOoc plugin.

Test moved from simplnx-ooc/test/OocMemoryBudgetManagerTest.cpp.

Author: joeykleingers

CMakeLists.txt

@@ -561,6 +561,7 @@ set(SIMPLNX_HDRS
   ${SIMPLNX_SOURCE_DIR}/Utilities/HistogramUtilities.hpp
   ${SIMPLNX_SOURCE_DIR}/Utilities/MaskCompareUtilities.hpp
   ${SIMPLNX_SOURCE_DIR}/Utilities/MemoryUtilities.hpp
+  ${SIMPLNX_SOURCE_DIR}/Utilities/MemoryBudgetManager.hpp
   ${SIMPLNX_SOURCE_DIR}/Utilities/MessageHelper.hpp
   ${SIMPLNX_SOURCE_DIR}/Utilities/StringUtilities.hpp
   ${SIMPLNX_SOURCE_DIR}/Utilities/StringInterpretationUtilities.hpp
@@ -767,6 +768,7 @@ set(SIMPLNX_SRCS
   ${SIMPLNX_SOURCE_DIR}/Utilities/DataStoreUtilities.cpp
   ${SIMPLNX_SOURCE_DIR}/Utilities/MaskCompareUtilities.cpp
   ${SIMPLNX_SOURCE_DIR}/Utilities/MemoryUtilities.cpp
+  ${SIMPLNX_SOURCE_DIR}/Utilities/MemoryBudgetManager.cpp
   ${SIMPLNX_SOURCE_DIR}/Utilities/MessageHelper.cpp
   ${SIMPLNX_SOURCE_DIR}/Utilities/IParallelAlgorithm.cpp
   ${SIMPLNX_SOURCE_DIR}/Utilities/ParallelDataAlgorithm.cpp

src/simplnx/Utilities/MemoryBudgetManager.cpp

@@ -0,0 +1,191 @@
+#include "simplnx/Utilities/MemoryBudgetManager.hpp"
+
+#include <algorithm>
+#include <limits>
+#include <stdexcept>
+
+#ifdef __APPLE__
+#include <sys/sysctl.h>
+#include <sys/types.h>
+#elif defined(__linux__)
+#include <fstream>
+#include <string>
+#elif defined(_WIN32)
+#define NOMINMAX
+#include <windows.h>
+#endif
+
+namespace nx::core
+{
+
+MemoryBudgetManager::MemoryBudgetManager()
+: m_BudgetBytes(defaultBudgetBytes())
+{
+}
+
+MemoryBudgetManager& MemoryBudgetManager::instance()
+{
+  static MemoryBudgetManager s_Instance;
+  return s_Instance;
+}
+
+uint64 MemoryBudgetManager::defaultBudgetBytes()
+{
+  static constexpr uint64 k_MinBudget = uint64{1} * 1024 * 1024 * 1024; // 1 GB
+
+  uint64 totalRam = 0;
+
+#ifdef __APPLE__
+  int mib[2] = {CTL_HW, HW_MEMSIZE};
+  uint64 memsize = 0;
+  size_t len = sizeof(memsize);
+  if(sysctl(mib, 2, &memsize, &len, nullptr, 0) == 0)
+  {
+    totalRam = memsize;
+  }
+#elif defined(__linux__)
+  std::ifstream meminfo("/proc/meminfo");
+  std::string line;
+  while(std::getline(meminfo, line))
+  {
+    if(line.find("MemTotal:") == 0)
+    {
+      // Format: "MemTotal:       12345678 kB"
+      uint64 kb = 0;
+      // Skip "MemTotal:" prefix and parse the number
+      auto pos = line.find_first_of("0123456789");
+      if(pos != std::string::npos)
+      {
+        try
+        {
+          kb = std::stoull(line.substr(pos));
+        } catch(const std::exception&)
+        {
+          return k_MinBudget;
+        }
+      }
+      totalRam = kb * 1024;
+      break;
+    }
+  }
+#elif defined(_WIN32)
+  MEMORYSTATUSEX memStatus;
+  memStatus.dwLength = sizeof(memStatus);
+  if(GlobalMemoryStatusEx(&memStatus))
+  {
+    totalRam = memStatus.ullTotalPhys;
+  }
+#endif
+
+  if(totalRam == 0)
+  {
+    return k_MinBudget;
+  }
+
+  uint64 halfRam = totalRam / 2;
+  return std::max(halfRam, k_MinBudget);
+}
+
+std::pair<MemoryBudgetManager::AllocationHandle, std::vector<MemoryBudgetManager::AllocationHandle>> MemoryBudgetManager::allocate(const std::string& subsystem, const std::string& key,
+                                                                                                                                   uint64 sizeBytes, EvictionCallback onEvict)
+{
+  std::lock_guard<std::mutex> lock(m_Mutex);
+
+  std::vector<AllocationHandle> evicted = makeRoom(sizeBytes);
+
+  AllocationHandle handle = m_NextHandle++;
+  Entry entry;
+  entry.subsystem = subsystem;
+  entry.key = key;
+  entry.sizeBytes = sizeBytes;
+  entry.lastAccessed = std::chrono::steady_clock::now();
+  entry.onEvict = std::move(onEvict);
+
+  m_Entries.emplace(handle, std::move(entry));
+  m_UsedBytes += sizeBytes;
+
+  return {handle, std::move(evicted)};
+}
+
+void MemoryBudgetManager::touch(AllocationHandle handle)
+{
+  std::lock_guard<std::mutex> lock(m_Mutex);
+  auto it = m_Entries.find(handle);
+  if(it != m_Entries.end())
+  {
+    it->second.lastAccessed = std::chrono::steady_clock::now();
+  }
+}
+
+void MemoryBudgetManager::release(AllocationHandle handle)
+{
+  std::lock_guard<std::mutex> lock(m_Mutex);
+  auto it = m_Entries.find(handle);
+  if(it != m_Entries.end())
+  {
+    m_UsedBytes -= it->second.sizeBytes;
+    m_Entries.erase(it);
+  }
+}
+
+void MemoryBudgetManager::setBudgetBytes(uint64 bytes)
+{
+  std::lock_guard<std::mutex> lock(m_Mutex);
+  m_BudgetBytes = bytes;
+}
+
+uint64 MemoryBudgetManager::budgetBytes() const
+{
+  std::lock_guard<std::mutex> lock(m_Mutex);
+  return m_BudgetBytes;
+}
+
+uint64 MemoryBudgetManager::usedBytes() const
+{
+  std::lock_guard<std::mutex> lock(m_Mutex);
+  return m_UsedBytes;
+}
+
+void MemoryBudgetManager::clear()
+{
+  std::lock_guard<std::mutex> lock(m_Mutex);
+  m_Entries.clear();
+  m_UsedBytes = 0;
+}
+
+std::vector<MemoryBudgetManager::AllocationHandle> MemoryBudgetManager::makeRoom(uint64 needed)
+{
+  std::vector<AllocationHandle> evicted;
+
+  while(!m_Entries.empty() && m_UsedBytes + needed > m_BudgetBytes)
+  {
+    // Find entry with oldest lastAccessed using a direct iterator
+    auto oldest = m_Entries.end();
+    for(auto it = m_Entries.begin(); it != m_Entries.end(); ++it)
+    {
+      if(oldest == m_Entries.end() || it->second.lastAccessed < oldest->second.lastAccessed)
+      {
+        oldest = it;
+      }
+    }
+
+    if(oldest == m_Entries.end())
+    {
+      break;
+    }
+
+    // Invoke eviction callback under mutex (must be non-blocking)
+    if(oldest->second.onEvict)
+    {
+      oldest->second.onEvict();
+    }
+
+    m_UsedBytes -= oldest->second.sizeBytes;
+    evicted.push_back(oldest->first);
+    m_Entries.erase(oldest);
+  }
+
+  return evicted;
+}
+
+} // namespace nx::core

src/simplnx/Utilities/MemoryBudgetManager.hpp

@@ -0,0 +1,135 @@
+#pragma once
+
+#include "simplnx/simplnx_export.hpp"
+
+#include "simplnx/Common/Types.hpp"
+
+#include <chrono>
+#include <functional>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+namespace nx::core
+{
+
+/**
+ * @brief Unified memory budget manager for cache subsystems across simplnx and visualization code.
+ *
+ * All cache subsystems (ChunkCache, stride cache, partition cache) register their
+ * allocations with this singleton. When memory pressure exceeds the budget, the
+ * manager evicts the globally-oldest entry regardless of which subsystem owns it.
+ *
+ * Thread-safe: allocate/touch/release can be called from any thread.
+ *
+ * Eviction callbacks are invoked under the manager's mutex and MUST be non-blocking
+ * (mark data for removal, don't do I/O or VTK operations). Callers receive the list
+ * of evicted handles after the mutex is released for post-eviction cleanup.
+ */
+class SIMPLNX_EXPORT MemoryBudgetManager
+{
+public:
+  using AllocationHandle = uint64;
+
+  /**
+   * @brief Callback invoked when an entry is evicted.
+   *
+   * The callback is invoked under the manager's internal mutex.
+   * Callbacks MUST NOT call allocate/touch/release on this manager -- that
+   * would deadlock (the mutex is not recursive). Only mark state for removal;
+   * do no I/O.
+   */
+  using EvictionCallback = std::function<void()>;
+
+  /**
+   * @brief Returns the singleton instance.
+   */
+  static MemoryBudgetManager& instance();
+
+  /**
+   * @brief Returns a default budget of 50% of system RAM, clamped to a minimum of 1 GB.
+   */
+  static uint64 defaultBudgetBytes();
+
+  /**
+   * @brief Allocates a tracked entry. Evicts oldest entries if needed to stay within budget.
+   * @param subsystem Name of the owning subsystem (e.g. "chunk", "stride", "partition")
+   * @param key Subsystem-specific key for identification
+   * @param sizeBytes Size of the allocation in bytes
+   * @param onEvict Callback invoked when this entry is evicted (must be non-blocking)
+   * @return Pair of (new handle, list of evicted handles for post-eviction cleanup)
+   */
+  std::pair<AllocationHandle, std::vector<AllocationHandle>> allocate(const std::string& subsystem, const std::string& key, uint64 sizeBytes, EvictionCallback onEvict);
+
+  /**
+   * @brief Updates the last-accessed timestamp of an allocation.
+   * @param handle The allocation handle to touch
+   */
+  void touch(AllocationHandle handle);
+
+  /**
+   * @brief Voluntarily releases an allocation.
+   * @param handle The allocation handle to release
+   */
+  void release(AllocationHandle handle);
+
+  /**
+   * @brief Sets the memory budget in bytes.
+   */
+  void setBudgetBytes(uint64 bytes);
+
+  /**
+   * @brief Returns the current memory budget in bytes.
+   */
+  uint64 budgetBytes() const;
+
+  /**
+   * @brief Returns the current total memory usage in bytes.
+   */
+  uint64 usedBytes() const;
+
+  /**
+   * @brief Clears all tracked entries and resets used bytes to zero.
+   *
+   * Intended for tests that share the mutable singleton -- call at the start
+   * of each test case so leaked entries from a prior failure do not pollute
+   * budget accounting.
+   */
+  void clear();
+
+private:
+  MemoryBudgetManager();
+  ~MemoryBudgetManager() = default;
+
+  MemoryBudgetManager(const MemoryBudgetManager&) = delete;
+  MemoryBudgetManager& operator=(const MemoryBudgetManager&) = delete;
+
+  struct Entry
+  {
+    std::string subsystem;
+    std::string key;
+    uint64 sizeBytes = 0;
+    std::chrono::steady_clock::time_point lastAccessed;
+    /// Eviction callback. MUST NOT call allocate/touch/release on this
+    /// manager -- that would deadlock. Only mark state for removal; do no I/O.
+    EvictionCallback onEvict;
+  };
+
+  /**
+   * @brief Evicts the oldest entries until m_UsedBytes + needed <= m_BudgetBytes.
+   * Must be called with m_Mutex held.
+   * @param needed Number of bytes needed for a new allocation
+   * @return List of evicted handles
+   */
+  std::vector<AllocationHandle> makeRoom(uint64 needed);
+
+  mutable std::mutex m_Mutex;
+  std::unordered_map<AllocationHandle, Entry> m_Entries;
+  uint64 m_BudgetBytes = 0;
+  uint64 m_UsedBytes = 0;
+  AllocationHandle m_NextHandle = 1;
+};
+
+} // namespace nx::core

test/CMakeLists.txt

@@ -41,6 +41,7 @@ add_executable(simplnx_test
   IntersectionUtilitiesTest.cpp
   IOFormat.cpp
   IParallelAlgorithmTest.cpp
+  MemoryBudgetManagerTest.cpp
   MontageTest.cpp
   NeighborUtilitiesTest.cpp
   PluginTest.cpp