Introduce Host::Memory.

Author: samuel-williams-shopify

lib/process/metrics/host/memory.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+module Process
+	module Metrics
+		# Per-host (system-wide) memory metrics. Use Host::Memory for total/used/free and swap; use Process::Metrics::Memory for per-process metrics.
+		module Host
+			# Struct for host memory snapshot. All sizes in bytes.
+			# @attribute total [Integer] Total memory (cgroup limit when in a container, else physical RAM).
+			# @attribute used [Integer] Memory in use (total - free).
+			# @attribute free [Integer] Available memory (MemAvailable-style: free + reclaimable).
+			# @attribute swap_total [Integer, nil] Total swap, or nil if not available.
+			# @attribute swap_used [Integer, nil] Swap in use, or nil if not available.
+			Memory = Struct.new(:total, :used, :free, :swap_total, :swap_used) do
+				alias as_json to_h
+				
+				def to_json(*arguments)
+					as_json.to_json(*arguments)
+				end
+				
+				# Create a zero-initialized Host::Memory instance.
+				# @returns [Memory]
+				def self.zero
+					self.new(0, 0, 0, nil, nil)
+				end
+				
+				# Whether host memory capture is supported on this platform.
+				# @returns [Boolean]
+				def self.supported?
+					false
+				end
+				
+				# Capture current host memory. Implemented by Host::Memory::Linux or Host::Memory::Darwin (in host/memory/linux.rb, host/memory/darwin.rb).
+				# @returns [Memory | Nil] A Host::Memory instance, or nil if not supported or capture failed.
+				def self.capture
+					return nil
+				end
+			end
+		end
+	end
+end
+
+if RUBY_PLATFORM.include?("linux")
+	require_relative "memory/linux"
+elsif RUBY_PLATFORM.include?("darwin")
+	require_relative "memory/darwin"
+end

lib/process/metrics/host/memory/darwin.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+module Process
+	module Metrics
+		module Host
+			# Darwin (macOS) implementation of host memory metrics.
+			# Uses sysctl (hw.memsize), vm_stat (free + inactive pages), and vm.swapusage for swap.
+			class Memory::Darwin
+				# Parse a size string from vm.swapusage (e.g. "1024.00M", "512.00K") into bytes.
+				# @parameter string [String | Nil] The size string from sysctl vm.swapusage.
+				# @returns [Integer | Nil] Size in bytes, or nil if string is nil/empty.
+				def self.parse_swap_size(string)
+					return nil unless string
+					
+					string = string.strip
+					
+					case string
+					when /([\d.]+)M/i then ($1.to_f * 1024 * 1024).round
+					when /([\d.]+)G/i then ($1.to_f * 1024 * 1024 * 1024).round
+					when /([\d.]+)K/i then ($1.to_f * 1024).round
+					else string.to_f.round
+					end
+				end
+				
+				# Capture current host memory. Reads total (hw.memsize), free (vm_stat), and swap (vm.swapusage).
+				# @returns [Host::Memory | Nil] A Host::Memory instance, or nil if capture fails.
+				def self.capture
+					total = capture_total
+					return nil unless total && total.positive?
+					
+					free = capture_free
+					return nil unless free
+					
+					free = 0 if free.negative?
+					used = [total - free, 0].max
+					swap_total, swap_used = capture_swap
+					
+					return Host::Memory.new(total, used, free, swap_total, swap_used)
+				end
+				
+				# Total physical RAM in bytes, from sysctl hw.memsize.
+				# @returns [Integer | Nil]
+				def self.capture_total
+					IO.popen(["sysctl", "-n", "hw.memsize"], "r", &:read)&.strip&.to_i
+				end
+				
+				# Free + inactive (reclaimable) memory in bytes, from vm_stat. Matches Linux MemAvailable semantics.
+				# @returns [Integer | Nil]
+				def self.capture_free
+					output = IO.popen(["vm_stat"], "r", &:read)
+					page_size = output[/page size of (\d+) bytes/, 1]&.to_i
+					return nil unless page_size && page_size.positive?
+					
+					pages_free = output[/Pages free:\s*(\d+)/, 1]&.to_i || 0
+					pages_inactive = output[/Pages inactive:\s*(\d+)/, 1]&.to_i || 0
+					return (pages_free + pages_inactive) * page_size
+				end
+				
+				# Swap total and used in bytes, from sysctl vm.swapusage (e.g. "total = 64.00M  used = 32.00M  free = 32.00M").
+				# @returns [Array(Integer | Nil, Integer | Nil)] [swap_total_bytes, swap_used_bytes], or [nil, nil] if unavailable.
+				def self.capture_swap
+					output = IO.popen(["sysctl", "-n", "vm.swapusage"], "r", &:read)
+					return [nil, nil] unless output
+					
+					total_string = output[/total\s*=\s*([\d.]+\s*[KMG]?)/i, 1]
+					used_string = output[/used\s*=\s*([\d.]+\s*[KMG]?)/i, 1]
+					swap_total = total_string ? parse_swap_size(total_string) : nil
+					swap_used = used_string ? parse_swap_size(used_string) : nil
+					
+					return swap_total, swap_used
+				end
+			end
+		end
+	end
+end
+
+# Wire Host::Memory to this implementation on Darwin.
+class << Process::Metrics::Host::Memory
+	def capture
+		Process::Metrics::Host::Memory::Darwin.capture
+	end
+	
+	def supported?
+		File.exist?("/usr/bin/vm_stat")
+	end
+end

lib/process/metrics/host/memory/linux.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+module Process
+	module Metrics
+		module Host
+			# Linux implementation of host memory metrics.
+			# Uses cgroups v2 (memory.max, memory.current) or cgroups v1 (memory.limit_in_bytes, memory.usage_in_bytes) when in a container;
+			# otherwise reads /proc/meminfo (MemTotal, MemAvailable/MemFree, SwapTotal/SwapFree). Parses meminfo once per capture and reuses it.
+			class Memory::Linux
+				# Threshold for distinguishing actual memory limits from "unlimited" sentinel values in cgroups v1.
+				# In cgroups v1, when memory.limit_in_bytes is set to unlimited (by writing -1), the kernel stores a very large sentinel near 2^63.
+				# Any value >= 2^60 (1 exabyte) is treated as unlimited and we fall back to /proc/meminfo.
+				# Reference: https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt
+				CGROUP_V1_UNLIMITED_THRESHOLD = 2**60
+				
+				def initialize
+					@meminfo = false
+				end
+				
+				# Capture current host memory. Reads total and used (from cgroup or meminfo), computes free, and parses swap from meminfo.
+				# @returns [Host::Memory | Nil]
+				def capture
+					total = capture_total
+					return nil unless total && total.positive?
+					
+					used = capture_used(total)
+					used = 0 if used.nil? || used.negative?
+					used = [used, total].min
+					free = total - used
+					
+					swap_total, swap_used = capture_swap
+					
+					return Host::Memory.new(total, used, free, swap_total, swap_used)
+				end
+				
+				private
+				
+				# Memoized /proc/meminfo contents. Used for total (MemTotal), used (via MemAvailable), and swap when not in a cgroup.
+				# @returns [String | Nil]
+				def meminfo
+					if @meminfo == false
+						@meminfo = File.read("/proc/meminfo") rescue nil
+					end
+					
+					return @meminfo
+				end
+				
+				# Total memory in bytes: cgroups v2 memory.max, cgroups v1 memory.limit_in_bytes (if < threshold), else MemTotal from meminfo.
+				# @returns [Integer | Nil]
+				def capture_total
+					if File.exist?("/sys/fs/cgroup/memory.max")
+						limit = File.read("/sys/fs/cgroup/memory.max").strip
+						return limit.to_i if limit != "max"
+					end
+					
+					if File.exist?("/sys/fs/cgroup/memory/memory.limit_in_bytes")
+						limit = File.read("/sys/fs/cgroup/memory/memory.limit_in_bytes").strip.to_i
+						return limit if limit > 0 && limit < CGROUP_V1_UNLIMITED_THRESHOLD
+					end
+					
+					unless meminfo = self.meminfo
+						return nil 
+					end
+					
+					meminfo.each_line do |line|
+						if /MemTotal:\s*(?<total>\d+)\s*kB/ =~ line
+							return $~[:total].to_i * 1024
+						end
+					end
+					
+					return nil
+				end
+				
+				# Current memory usage in bytes: cgroups v2 memory.current, cgroups v1 memory.usage_in_bytes, or total - MemAvailable from meminfo.
+				# @parameter total [Integer] Total memory (used to compute used from MemAvailable when not in cgroup).
+				# @returns [Integer | Nil]
+				def capture_used(total)
+					if File.exist?("/sys/fs/cgroup/memory.current")
+						current = File.read("/sys/fs/cgroup/memory.current").strip.to_i
+						return current
+					end
+					
+					if File.exist?("/sys/fs/cgroup/memory/memory.usage_in_bytes")
+						limit = File.read("/sys/fs/cgroup/memory/memory.limit_in_bytes").strip.to_i
+						if limit > 0 && limit < CGROUP_V1_UNLIMITED_THRESHOLD
+							return File.read("/sys/fs/cgroup/memory/memory.usage_in_bytes").strip.to_i
+						end
+					end
+					
+					unless meminfo = self.meminfo
+						return nil 
+					end
+					
+					available_kb = meminfo[/MemAvailable:\s*(\d+)\s*kB/, 1]&.to_i
+					available_kb ||= meminfo[/MemFree:\s*(\d+)\s*kB/, 1]&.to_i
+					return nil unless available_kb
+					
+					return [total - (available_kb * 1024), 0].max
+				end
+				
+				# Swap total and used in bytes from meminfo (SwapTotal, SwapFree).
+				# @returns [Array(Integer, Integer)] [swap_total_bytes, swap_used_bytes], or [nil, nil] if no swap.
+				def capture_swap
+					return [nil, nil] unless meminfo
+					swap_total_kb = meminfo[/SwapTotal:\s*(\d+)\s*kB/, 1]&.to_i
+					swap_free_kb = meminfo[/SwapFree:\s*(\d+)\s*kB/, 1]&.to_i
+					
+					return [nil, nil] unless swap_total_kb
+					
+					swap_total_bytes = swap_total_kb * 1024
+					swap_used_bytes = (swap_total_kb - (swap_free_kb || 0)) * 1024
+					
+					return swap_total_bytes, swap_used_bytes
+				end
+			end
+		end
+	end
+end
+
+# Wire Host::Memory to this implementation on Linux.
+class << Process::Metrics::Host::Memory
+	def capture
+		Process::Metrics::Host::Memory::Linux.new.capture
+	end
+	
+	def supported?
+		File.exist?("/proc/meminfo")
+	end
+end

lib/process/metrics/memory.rb

@@ -4,6 +4,7 @@
 # Copyright, 2019-2026, by Samuel Williams.
 
 require "json"
+require_relative "host/memory"
 
 module Process
 	module Metrics
@@ -33,6 +34,12 @@ def self.zero
 				self.new(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
 			end
 
+			# Total system/host memory in bytes. Delegates to Host::Memory.capture.
+			# @returns [Integer | Nil]
+			def self.total_size
+				Host::Memory.capture&.total
+			end
+			
 			# Whether the memory usage can be captured on this system.
 			def self.supported?
 				false
@@ -46,5 +53,8 @@ def self.capture(pid, **options)
 	end
 end
 
-require_relative "memory/linux"
-require_relative "memory/darwin"
+if RUBY_PLATFORM.include?("linux")
+	require_relative "memory/linux"
+elsif RUBY_PLATFORM.include?("darwin")
+	require_relative "memory/darwin"
+end