memory-leak 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 831ea4087e21cc1b7a9ba7b7dadd3239b1b3ef77aa6a9eccb26392880b2b4068
-  data.tar.gz: 680ec100fe3017a15a8fc9b5e75c68c70e8d28e46a439737f0e4e53e715da9a9
+  metadata.gz: 14b3c3712d827c78c74132d04b0488e5572ede9a4ff1451e5df6990c8931007f
+  data.tar.gz: f055ae13339a94c15fe4ee52ec264cde3e6ab764e84e3f358e94477c3f3e5753
 SHA512:
-  metadata.gz: 86abd84862289e63d20123f222b35493c051f4daa0f15e386e988b1269702dae0f888a4113d8f97fbf0c9d4240cf0c061d478e4a709436e497c0736dfbca250c
-  data.tar.gz: b8d92826ffd0aa9fb42dc3209e60d46fc685f739c3c1f4a5688b4a013f8e7c075fb39a47afb248e00c48c9f1e62c19ff6bb0bee992e127885a56a525dc2c3d4a
+  metadata.gz: cd92451ab8a82bc932279eff5d76c8a2b9e9b792bcc77e663b867a9ab8cbb9640dbe0b343841b1fdb74e770e1bf53abddbcd060bcfccecf47679c69cba5ddd57
+  data.tar.gz: de5bd472ca16f2819c991c9d5b542da3d5a62c161bd1d4b64098f14a956f980cbb5db247a749512f35a982eeae0a265f2ceffbbaf60485adfeb17a060530eb55

data/lib/memory/leak/cluster.rb

@@ -14,9 +14,10 @@ module Memory
 		class Cluster
 			# Create a new cluster.
 			#
-			# @parameter limit [Numeric | Nil] The (total) memory limit for the cluster.
-			def initialize(limit: nil)
-				@limit = limit
+			# @parameter total_size_limit [Numeric | Nil] The total memory limit for the cluster.
+			def initialize(total_size_limit: nil)
+				@total_size = nil
+				@total_size_limit = total_size_limit
 				
 				@processes = {}
 			end
@@ -24,7 +25,8 @@ module Memory
 			# @returns [Hash] A serializable representation of the cluster.
 			def as_json(...)
 				{
-					limit: @limit,
+					total_size: @total_size,
+					total_size_limit: @total_size_limit,
 					processes: @processes.transform_values(&:as_json),
 				}
 			end
@@ -34,8 +36,11 @@ module Memory
 				as_json.to_json(...)
 			end
 			
-			# @attribute [Numeric | Nil] The memory limit for the cluster.
-			attr_accessor :limit
+			# @attribute [Numeric | Nil] The total size of the cluster.
+			attr :total_size
+			
+			# @attribute [Numeric | Nil] The total size limit for the cluster, in bytes, if which is exceeded, the cluster will terminate processes.
+			attr_accessor :total_size_limit
 			
 			# @attribute [Hash(Integer, Monitor)] The process IDs and monitors in the cluster.
 			attr :processes
@@ -53,37 +58,49 @@ module Memory
 			# Apply the memory limit to the cluster. If the total memory usage exceeds the limit, yields each process ID and monitor in order of maximum memory usage, so that they could be terminated and/or removed.
 			#
 			# @yields {|process_id, monitor| ...} each process ID and monitor in order of maximum memory usage, return true if it was terminated to adjust memory usage.
-			def apply_limit!(limit = @limit)
-				total = @processes.values.map(&:current).sum
+			def apply_limit!(total_size_limit = @total_size_limit)
+				@total_size = @processes.values.map(&:current_size).sum
 				
-				if total > limit
-					Console.warn(self, "Total memory usage exceeded limit.", total: total, limit: limit)
+				if @total_size > total_size_limit
+					Console.warn(self, "Total memory usage exceeded limit.", total_size: @total_size, total_size_limit: total_size_limit)
+				else
+					return false
 				end
 				
 				sorted = @processes.sort_by do |process_id, monitor|
-					-monitor.current
+					-monitor.current_size
 				end
 				
 				sorted.each do |process_id, monitor|
-					if total > limit
-						if yield process_id, monitor, total
-							total -= monitor.current
-						end
+					if @total_size > total_size_limit
+						yield(process_id, monitor, @total_size)
+						
+						# For the sake of the calculation, we assume that the process has been terminated:
+						@total_size -= monitor.current_size
 					else
 						break
 					end
 				end
 			end
 			
+			# Sample the memory usage of all processes in the cluster.
+			def sample!
+				System.memory_usages(@processes.keys).each do |process_id, memory_usage|
+					@processes[process_id].current_size = memory_usage
+				end
+			end
+			
 			# Check all processes in the cluster for memory leaks.
 			#
 			# @yields {|process_id, monitor| ...} each process ID and monitor that is leaking or exceeds the memory limit.
 			def check!(&block)
+				return to_enum(__method__) unless block_given?
+				
+				self.sample!
+				
 				leaking = []
 				
 				@processes.each do |process_id, monitor|
-					monitor.sample!
-					
 					if monitor.leaking?
 						Console.debug(self, "Memory Leak Detected!", process_id: process_id, monitor: monitor)
 						
@@ -94,7 +111,7 @@ module Memory
 				leaking.each(&block)
 				
 				# Finally, apply any per-cluster memory limits:
-				apply_limit!(@limit, &block) if @limit
+				apply_limit!(@total_size_limit, &block) if @total_size_limit
 			end
 		end
 	end

data/lib/memory/leak/monitor.rb

@@ -4,51 +4,54 @@
 # Copyright, 2025, by Samuel Williams.
 
 require "console"
+require_relative "system"
 
 module Memory
 	module Leak
-		# Detects memory leaks by tracking heap size increases.
+		# Detects memory leaks by tracking process size increases.
 		#
 		# A memory leak is characterised by the memory usage of the application continuing to rise over time. We can detect this by sampling memory usage and comparing it to the previous sample. If the memory usage is higher than the previous sample, we can say that the application has allocated more memory. Eventually we expect to see this stabilize, but if it continues to rise, we can say that the application has a memory leak.
 		#
 		# We should be careful not to filter historical data, as some memory leaks may only become apparent after a long period of time. Any kind of filtering may prevent us from detecting such a leak.
 		class Monitor
-			# We only track heap size changes greater than this threshold, across the DEFAULT_INTERVAL.
-			# True memory leaks will eventually hit this threshold, while small fluctuations will not.
-			DEFAULT_THRESHOLD = 1024*1024*10
+			# We only track process size changes greater than this threshold_size, across the DEFAULT_INTERVAL.
+			# True memory leaks will eventually hit this threshold_size, while small fluctuations will not.
+			DEFAULT_THRESHOLD_SIZE = 1024*1024*10
 			
-			# We track the last N heap size increases.
-			# If the heap size is not stabilizing within the specified limit, we can assume there is a leak.
-			# With a default interval of 10 seconds, this will track the last ~3 minutes of heap size increases.
-			DEFAULT_LIMIT = 20
+			# We track the last N process size increases.
+			# If the process size is not stabilizing within the specified increase_limit, we can assume there is a leak.
+			# With a default interval of 10 seconds, this will track the last ~3 minutes of process size increases.
+			DEFAULT_INCREASE_LIMIT = 20
 			
 			# Create a new monitor.
 			#
-			# @parameter maximum [Numeric] The initial maximum heap size, from which we willl track increases, in bytes.
-			# @parameter threshold [Numeric] The threshold for heap size increases, in bytes.
-			# @parameter limit [Numeric] The limit for the number of heap size increases, before we assume a memory leak.
-			# @parameter [Integer] The process ID to monitor.
-			def initialize(process_id = Process.pid, maximum: nil, threshold: DEFAULT_THRESHOLD, limit: DEFAULT_LIMIT)
+			# @parameter process_id [Integer] The process ID to monitor.
+			# @parameter maximum_size [Numeric] The initial process size, from which we willl track increases, in bytes.
+			# @parameter maximum_size_limit [Numeric | Nil] The maximum process size allowed, in bytes, before we assume a memory leak.
+			# @parameter threshold_size [Numeric] The threshold for process size increases, in bytes.
+			# @parameter increase_limit [Numeric] The limit for the number of process size increases, before we assume a memory leak.
+			def initialize(process_id = Process.pid, maximum_size: nil, maximum_size_limit: nil, threshold_size: DEFAULT_THRESHOLD_SIZE, increase_limit: DEFAULT_INCREASE_LIMIT)
 				@process_id = process_id
 				
-				@maximum = maximum
-				@threshold = threshold
-				@limit = limit
+				@current_size = nil
+				@maximum_size = maximum_size
+				@maximum_size_limit = maximum_size_limit
 				
-				# The number of increasing heap size samples.
-				@count = 0
-				@current = nil
+				@threshold_size = threshold_size
+				@increase_count = 0
+				@increase_limit = increase_limit
 			end
 			
 			# @returns [Hash] A serializable representation of the cluster.
 			def as_json(...)
 				{
 					process_id: @process_id,
-					current: @current,
-					maximum: @maximum,
-					threshold: @threshold,
-					limit: @limit,
-					count: @count,
+					current_size: @current_size,
+					maximum_size: @maximum_size,
+					maximum_size_limit: @maximum_size_limit,
+					threshold_size: @threshold_size,
+					increase_count: @increase_count,
+					increase_limit: @increase_limit,
 				}
 			end
 			
@@ -60,65 +63,81 @@ module Memory
 			# @attribute [Integer] The process ID to monitor.
 			attr :process_id
 			
-			# @attribute [Numeric] The current maximum heap size.
-			attr :maximum
+			# @attribute [Numeric] The maximum process size observed.
+			attr_accessor :maximum_size
 			
-			# @attribute [Numeric] The threshold for heap size increases.
-			attr :threshold
+			# @attribute [Numeric | Nil] The maximum process size allowed, before we assume a memory leak.
+			attr_accessor :maximum_size_limit
 			
-			# @attribute [Numeric] The limit for the number of heap size increases, before we assume a memory leak.
-			attr :limit
+			# @attribute [Numeric] The threshold_size for process size increases.
+			attr_accessor :threshold_size
 			
-			# @attribute [Integer] The number of increasing heap size samples. 
-			attr :count
+			# @attribute [Integer] The number of increasing process size samples. 
+			attr_accessor :increase_count
 			
-			# The current resident set size (RSS) of the process.
-			#
-			# Even thought the absolute value of this number may not very useful, the relative change is useful for detecting memory leaks, and it works on most platforms.
-			#
-			# @returns [Numeric] Memory usage size in bytes.
-			private def memory_usage
-				IO.popen(["ps", "-o", "rss=", @process_id.to_s]) do |io|
-					return Integer(io.readlines.last) * 1024
-				end
+			# @attribute [Numeric] The limit for the number of process size increases, before we assume a memory leak.
+			attr_accessor :increase_limit
+			
+			# @returns [Integer] Ask the system for the current memory usage.
+			def memory_usage
+				System.memory_usage(@process_id)
 			end
 			
 			# @returns [Integer] The last sampled memory usage.
-			def current
-				@current ||= memory_usage
+			def current_size
+				@current_size ||= memory_usage
+			end
+			
+			# Set the current memory usage, rather than sampling it.
+			def current_size=(value)
+				@current_size = value
 			end
 			
 			# Indicates whether a memory leak has been detected.
 			#
-			# If the number of increasing heap size samples is greater than or equal to the limit, a memory leak is assumed.
+			# If the number of increasing heap size samples is greater than or equal to the increase_limit, a memory leak is assumed.
+			#
+			# @returns [Boolean] True if a memory leak has been detected.
+			def increase_limit_exceeded?
+				@increase_count >= @increase_limit
+			end
+			
+			# Indicates that the current memory usage has grown beyond the maximum size limit.
+			#
+			# @returns [Boolean] True if the current memory usage has grown beyond the maximum size limit.
+			def maximum_size_limit_exceeded?
+				@maximum_size_limit && self.current_size > @maximum_size_limit
+			end
+			
+			# Indicates whether a memory leak has been detected.
 			#
 			# @returns [Boolean] True if a memory leak has been detected.
 			def leaking?
-				@count >= @limit
+				increase_limit_exceeded? || maximum_size_limit_exceeded?
 			end
 			
 			# Capture a memory usage sample and yield if a memory leak is detected.
 			#
 			# @yields {|sample, monitor| ...} If a memory leak is detected.
 			def sample!
-				@current = memory_usage
+				self.current_size = memory_usage
 				
-				if @maximum
-					delta = @current - @maximum
-					Console.debug(self, "Heap size captured.", current: @current, delta: delta, threshold: @threshold, maximum: @maximum)
+				if @maximum_observed_size
+					delta = @current_size - @maximum_observed_size
+					Console.debug(self, "Heap size captured.", current_size: @current_size, delta: delta, threshold_size: @threshold_size, maximum_observed_size: @maximum_observed_size)
 					
-					if delta > @threshold
-						@maximum = @current
-						@count += 1
+					if delta > @threshold_size
+						@maximum_observed_size = @current_size
+						@increase_count += 1
 						
-						Console.debug(self, "Heap size increased.", maximum: @maximum, count: @count)
+						Console.debug(self, "Heap size increased.", maximum_observed_size: @maximum_observed_size, count: @count)
 					end
 				else
-					Console.debug(self, "Initial heap size captured.", current: @current)
-					@maximum = @current
+					Console.debug(self, "Initial heap size captured.", current_size: @current_size)
+					@maximum_observed_size = @current_size
 				end
 				
-				return @current
+				return @current_size
 			end
 		end
 	end

data/lib/memory/leak/system.rb

@@ -7,18 +7,19 @@ require "console"
 
 module Memory
 	module Leak
+		# System-specific memory information.
 		module System
 			if File.exist?("/proc/meminfo")
+				# @returns [Integer] The total memory size in bytes.
 				def self.total_memory_size
 					File.foreach("/proc/meminfo") do |line|
 						if /MemTotal:\s*(?<total>\d+)\s*kB/ =~ line
 							return total.to_i * 1024
 						end
 					end
-					
-					return nil
 				end
 			elsif RUBY_PLATFORM =~ /darwin/
+				# @returns [Integer] The total memory size in bytes.
 				def self.total_memory_size
 					IO.popen(["sysctl", "hw.memsize"], "r") do |io|
 						io.each_line do |line|
@@ -29,6 +30,26 @@ module Memory
 					end
 				end
 			end
+			
+			# Get the memory usage of the given process IDs.
+			#
+			# @parameter process_ids [Array(Integer)] The process IDs to monitor.
+			# @returns [Array(Tuple(Integer, Integer))] The memory usage of the given process IDs.
+			def self.memory_usages(process_ids)
+				IO.popen(["ps", "-o", "pid=,rss=", *process_ids.map(&:to_s)]) do |io|
+					io.each_line.map(&:split).map{|process_id, size| [process_id.to_i, size.to_i * 1024]}
+				end
+			end
+			
+			# Get the memory usage of the given process IDs.
+			#
+			# @parameter process_ids [Array(Integer)] The process IDs to monitor.
+			# @returns [Array(Tuple(Integer, Integer))] The memory usage of the given process IDs.
+			def self.memory_usage(process_id)
+				IO.popen(["ps", "-o", "rss=", process_id.to_s]) do |io|
+					return io.read.to_i * 1024
+				end
+			end
 		end
 	end
 end

data/lib/memory/leak/version.rb

@@ -5,6 +5,6 @@
 
 module Memory
 	module Leak
-		VERSION = "0.4.0"
+		VERSION = "0.5.0"
 	end
 end

data/readme.md

@@ -12,6 +12,11 @@ Please see the [project documentation](https://socketry.github.io/memory-leak/)
 
 Please see the [project releases](https://socketry.github.io/memory-leak/releases/index) for all releases.
 
+### v0.5.0
+
+  - Improved variable names.
+  - Added `maximum_size_limit` to process monitor.
+
 ### v0.1.0
 
   - Initial implementation.

data/releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## v0.5.0
+
+  - Improved variable names.
+  - Added `maximum_size_limit` to process monitor.
+
 ## v0.1.0
 
   - Initial implementation.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memory-leak
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -36,7 +36,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-02-26 00:00:00.000000000 Z
+date: 2025-02-28 00:00:00.000000000 Z
 dependencies: []
 executables: []
 extensions: []