Add Memory.free_size.

Author: samuel-williams-shopify

lib/process/metrics/memory.rb

@@ -33,6 +33,12 @@ def self.zero
 				self.new(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
 			end
 
+			# Get free (available) system memory in bytes. Overridden on Linux; returns nil when not available.
+			# @returns [Integer, nil]
+			def self.free_size
+				nil
+			end
+			
 			# Whether the memory usage can be captured on this system.
 			def self.supported?
 				false

lib/process/metrics/memory/darwin.rb

@@ -26,6 +26,17 @@ def self.total_size
 				end
 			end
 
+			# Free (available) memory in bytes. Uses vm_stat: free + inactive pages (reclaimable), matching Linux MemAvailable semantics.
+			# @returns [Integer, nil] Free memory in bytes, or nil if vm_stat is unavailable.
+			def self.free_size
+				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
+				(pages_free + pages_inactive) * page_size
+			end
+			
 			# Parse a size string from vmmap output into bytes.
 			# @parameter string [String | Nil] The size string (e.g., "4K", "1.5M", "2G").
 			# @returns [Integer] The size in bytes.
@@ -116,6 +127,12 @@ def total_size
 					return Memory::Darwin.total_size
 				end
 
+				# Get free (available) memory size.
+				# @returns [Integer, nil] Free memory in bytes, or nil if not determinable.
+				def free_size
+					return Memory::Darwin.free_size
+				end
+				
 				# Capture memory metrics for a process.
 				# @parameter pid [Integer] The process ID.
 				# @parameter options [Hash] Additional options (e.g., count for proportional estimates).

lib/process/metrics/memory/linux.rb

@@ -69,6 +69,43 @@ def self.total_size
 				end
 			end
 
+			# Determine the free (available) memory size in bytes. This is memory that can be used without reclaiming. When in a container, this is limit minus current usage; otherwise it uses MemAvailable from /proc/meminfo (includes reclaimable cache).
+			#
+			# @returns [Integer | Nil] The free memory size in bytes, or nil if not determinable.
+			def self.free_size
+				# cgroups v2: free = max - current (when max is set):
+				if File.exist?("/sys/fs/cgroup/memory.max")
+					limit = File.read("/sys/fs/cgroup/memory.max").strip
+					if limit != "max" && File.exist?("/sys/fs/cgroup/memory.current")
+						current = File.read("/sys/fs/cgroup/memory.current").strip.to_i
+						return [limit.to_i - current, 0].max
+					end
+				end
+				
+				# cgroups v1: free = limit - usage (when limit is set):
+				if File.exist?("/sys/fs/cgroup/memory/memory.limit_in_bytes") && 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
+						usage = File.read("/sys/fs/cgroup/memory/memory.usage_in_bytes").strip.to_i
+						return [limit - usage, 0].max
+					end
+				end
+				
+				# Fall back to /proc/meminfo: MemAvailable (reclaimable + free) or MemFree:
+				if File.exist?("/proc/meminfo")
+					meminfo = File.read("/proc/meminfo")
+					if /MemAvailable:\s*(?<avail>\d+)\s*kB/ =~ meminfo
+						return avail.to_i * 1024
+					end
+					if /MemFree:\s*(?<free>\d+)\s*kB/ =~ meminfo
+						return free.to_i * 1024
+					end
+				end
+				
+				# Unknown, return nil:
+				return nil
+			end
+			
 			# The fields that will be extracted from the `smaps` data.
 			SMAP = {
 				"Rss" => :resident_size,
@@ -177,6 +214,12 @@ def total_size
 					return Memory::Linux.total_size
 				end
 
+				# Get free (available) memory size.
+				# @returns [Integer, nil] Free memory in bytes, or nil if not determinable.
+				def free_size
+					return Memory::Linux.free_size
+				end
+				
 				# Capture memory metrics for a process.
 				# @parameter pid [Integer] The process ID.
 				# @parameter faults [Boolean] Whether to capture fault counters (default: true).

releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## Unreleased
+
+  - Added `Process::Metrics::Memory.free_size` for free/available system memory in bytes.
+
 ## v0.9.0
 
   - `Process::Metrics::Memory.total_size` takes into account cgroup limits.

test/process/memory.rb

@@ -7,9 +7,29 @@
 
 describe Process::Metrics::Memory do
 	with ".total_size" do
-		it "can get the total available memory" do
+		it "returns total available memory in bytes" do
 			expect(Process::Metrics::Memory.total_size).to be > 0
 		end
+		
+		it "returns an integer" do
+			expect(Process::Metrics::Memory.total_size).to be_a(Integer)
+		end
+	end
+	
+	with ".free_size" do
+		it "returns free/available memory in bytes when supported" do
+			free = Process::Metrics::Memory.free_size
+			skip "free_size is not available on this platform" if free.nil?
+			expect(free).to be_a(Integer)
+			expect(free).to be >= 0
+		end
+		
+		it "returns free size less than or equal to total size when both are available" do
+			total = Process::Metrics::Memory.total_size
+			free = Process::Metrics::Memory.free_size
+			skip "free_size is not available on this platform" if free.nil?
+			expect(free).to be <= total
+		end
 	end
 
 	with ".capture" do