ENH: Add GetSystemMemoryInfo() to MemoryUtilities

imikejackson · claude · imikejackson · commit 5764cfd48297 · 2026-03-03T12:33:59.000-05:00
Extend nx::core::Memory with a SystemMemoryInfo struct and
GetSystemMemoryInfo() function that returns a cross-platform snapshot of:
  - totalGB    — total installed physical RAM
  - usedGB     — currently used RAM (total - available)
  - loadPercent — system memory load percentage
  - processGB  — resident memory of the current process

Platform implementations:
  - Windows: GlobalMemoryStatusEx + GetProcessMemoryInfo (WorkingSetSize)
  - macOS:   hw.memsize sysctl, HOST_VM_INFO64 vm_statistics,
             TASK_VM_INFO phys_footprint
  - Linux:   /proc/meminfo (free-command formula) + /proc/self/statm

No Qt dependency; pure C++ / OS headers only.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/src/simplnx/Utilities/MemoryUtilities.cpp b/src/simplnx/Utilities/MemoryUtilities.cpp
@@ -3,7 +3,15 @@
 #if defined(_WIN32)
 #include <cstdlib>
 #include <windows.h>
+
+#include <psapi.h>
+#elif defined(__APPLE__)
+#include <mach/mach.h>
+#include <sys/sysctl.h>
+#include <unistd.h>
 #else
+#include <fstream>
+#include <sstream>
 #include <unistd.h>
 #endif
 
@@ -59,4 +67,155 @@ dataStorage GetAvailableStorageOnDrive(const std::filesystem::path& directory)
   return storage;
 }
 #endif
+
+// =============================================================================
+// GetSystemMemoryInfo — platform implementations
+// =============================================================================
+
+#if defined(_WIN32)
+
+SystemMemoryInfo GetSystemMemoryInfo()
+{
+  SystemMemoryInfo info;
+
+  MEMORYSTATUSEX memStatus;
+  memStatus.dwLength = sizeof(MEMORYSTATUSEX);
+  if(GlobalMemoryStatusEx(&memStatus))
+  {
+    info.totalGB = static_cast<double>(memStatus.ullTotalPhys) / (1024.0 * 1024.0 * 1024.0);
+    const double availableGB = static_cast<double>(memStatus.ullAvailPhys) / (1024.0 * 1024.0 * 1024.0);
+    info.usedGB = info.totalGB - availableGB;
+    info.loadPercent = static_cast<double>(memStatus.dwMemoryLoad);
+  }
+
+  PROCESS_MEMORY_COUNTERS_EX pmc;
+  const HANDLE hProcess = GetCurrentProcess();
+  if(GetProcessMemoryInfo(hProcess, reinterpret_cast<PROCESS_MEMORY_COUNTERS*>(&pmc), sizeof(pmc)))
+  {
+    info.processGB = static_cast<double>(pmc.WorkingSetSize) / (1024.0 * 1024.0 * 1024.0);
+  }
+
+  return info;
+}
+
+#elif defined(__APPLE__)
+
+namespace
+{
+// Helper: read a 64-bit integer sysctl value by name.
+int sysctlInt64(const char* name, int64_t* value)
+{
+  size_t len = sizeof(int64_t);
+  return sysctlbyname(name, value, &len, nullptr, 0);
+}
+} // namespace
+
+SystemMemoryInfo GetSystemMemoryInfo()
+{
+  SystemMemoryInfo info;
+
+  int64_t tempInt64 = 0;
+
+  if(sysctlInt64("hw.memsize", &tempInt64) != 0)
+  {
+    return info;
+  }
+  info.totalGB = static_cast<double>(tempInt64) / (1024.0 * 1024.0 * 1024.0);
+
+  vm_statistics64_data_t vmstat;
+  mach_msg_type_number_t count = HOST_VM_INFO64_COUNT;
+  if(host_statistics64(mach_host_self(), HOST_VM_INFO64, reinterpret_cast<host_info64_t>(&vmstat), &count) == KERN_SUCCESS)
+  {
+    if(sysctlInt64("hw.pagesize", &tempInt64) == 0)
+    {
+      const int64_t availableBytes = (static_cast<int64_t>(vmstat.free_count) + static_cast<int64_t>(vmstat.inactive_count)) * tempInt64;
+      const double availableGB = static_cast<double>(availableBytes) / (1024.0 * 1024.0 * 1024.0);
+      info.usedGB = info.totalGB - availableGB;
+      if(info.totalGB > 0.0)
+      {
+        info.loadPercent = info.usedGB * 100.0 / info.totalGB;
+      }
+    }
+  }
+
+  task_vm_info_data_t taskInfo;
+  mach_msg_type_number_t taskCount = TASK_VM_INFO_COUNT;
+  if(task_info(mach_task_self(), TASK_VM_INFO, reinterpret_cast<task_info_t>(&taskInfo), &taskCount) == KERN_SUCCESS)
+  {
+    info.processGB = static_cast<double>(taskInfo.phys_footprint) / (1024.0 * 1024.0 * 1024.0);
+  }
+
+  return info;
+}
+
+#else // Linux
+
+SystemMemoryInfo GetSystemMemoryInfo()
+{
+  SystemMemoryInfo info;
+
+  // Parse /proc/meminfo for system-wide memory figures
+  {
+    std::ifstream file("/proc/meminfo");
+    if(!file.is_open())
+    {
+      return info;
+    }
+
+    uint64_t memTotal = 0;
+    uint64_t memFree = 0;
+    uint64_t buffers = 0;
+    uint64_t cached = 0;
+    uint64_t sReclaimable = 0;
+
+    std::string line;
+    while(std::getline(file, line))
+    {
+      std::istringstream iss(line);
+      std::string key;
+      uint64_t value = 0;
+      std::string unit;
+      iss >> key >> value >> unit;
+
+      if(key == "MemTotal:")
+        memTotal = value;
+      else if(key == "MemFree:")
+        memFree = value;
+      else if(key == "Buffers:")
+        buffers = value;
+      else if(key == "Cached:")
+        cached = value;
+      else if(key == "SReclaimable:")
+        sReclaimable = value;
+    }
+
+    // Match the 'used' calculation from the 'free' command:
+    // used = total - (free + buffers + cached + SReclaimable)
+    const uint64_t usedKB = memTotal - (memFree + buffers + cached + sReclaimable);
+    info.totalGB = static_cast<double>(memTotal) / (1024.0 * 1024.0);
+    info.usedGB = static_cast<double>(usedKB) / (1024.0 * 1024.0);
+    if(info.totalGB > 0.0)
+    {
+      info.loadPercent = info.usedGB * 100.0 / info.totalGB;
+    }
+  }
+
+  // Read current process resident set size from /proc/self/statm
+  {
+    std::ifstream statm("/proc/self/statm");
+    if(statm.is_open())
+    {
+      unsigned long long totalPages = 0;
+      unsigned long long residentPages = 0;
+      statm >> totalPages >> residentPages;
+      const long pageSizeBytes = sysconf(_SC_PAGESIZE);
+      info.processGB = static_cast<double>(residentPages) * static_cast<double>(pageSizeBytes) / (1024.0 * 1024.0 * 1024.0);
+    }
+  }
+
+  return info;
+}
+
+#endif
+
 } // namespace nx::core::Memory
diff --git a/src/simplnx/Utilities/MemoryUtilities.hpp b/src/simplnx/Utilities/MemoryUtilities.hpp
@@ -9,14 +9,71 @@ namespace nx::core
 {
 namespace Memory
 {
+
+/**
+ * @brief Holds a total capacity and free-space measurement for a storage
+ * device or filesystem, in bytes.
+ */
 struct SIMPLNX_EXPORT dataStorage
 {
-  uint64_t total = 0;
-  uint64_t free = 0;
+  uint64_t total = 0; ///< Total capacity of the storage device in bytes.
+  uint64_t free = 0;  ///< Available (free) space on the storage device in bytes.
 };
 
+/**
+ * @brief Returns the total amount of physical RAM installed in the system.
+ *
+ * @return Total physical memory in bytes.
+ */
 uint64 SIMPLNX_EXPORT GetTotalMemory();
+
+/**
+ * @brief Returns the total and free space on the default temporary storage
+ * device (equivalent to calling GetAvailableStorageOnDrive() with the
+ * platform's temporary directory path).
+ *
+ * @return dataStorage containing total and free bytes on the temp drive.
+ * @see GetAvailableStorageOnDrive()
+ */
 dataStorage SIMPLNX_EXPORT GetAvailableStorage();
+
+/**
+ * @brief Returns the total and free space on the filesystem that contains
+ * @p path.
+ *
+ * @param path Any path that resides on the drive or filesystem to query.
+ *             On Windows this determines the drive letter; on POSIX systems
+ *             it determines the mount point.
+ * @return dataStorage containing total and free bytes on the queried drive.
+ * @see GetAvailableStorage()
+ */
 dataStorage SIMPLNX_EXPORT GetAvailableStorageOnDrive(const std::filesystem::path& path);
+
+/**
+ * @brief Snapshot of system-wide and per-process memory statistics.
+ *
+ * All memory quantities are expressed in gigabytes (GB).
+ */
+struct SIMPLNX_EXPORT SystemMemoryInfo
+{
+  double totalGB = 0.0;     ///< Total installed physical RAM in GB.
+  double usedGB = 0.0;      ///< Currently used physical RAM in GB (total - available).
+  double loadPercent = 0.0; ///< System memory load as a percentage in the range [0, 100].
+  double processGB = 0.0;   ///< Resident memory used by the current process in GB.
+};
+
+/**
+ * @brief Query the operating system for a current snapshot of system and
+ * process memory usage.
+ *
+ * Supported platforms: Windows, macOS, Linux (/proc/meminfo).
+ * Returns a zero-initialised struct on any platform error.
+ *
+ * @return SystemMemoryInfo containing total RAM, used RAM, memory load
+ *         percentage, and the calling process's resident memory.
+ * @see SystemMemoryInfo
+ */
+SIMPLNX_EXPORT SystemMemoryInfo GetSystemMemoryInfo();
+
 } // namespace Memory
 } // namespace nx::core
