Improve naming conventions.

- Extract `memory_usage` into `System` module.
- Add `memory_usages` for cluster monitoring.
- Add `maximum_size_limit` per monitor.

Author: ioquatix

lib/memory/leak/cluster.rb

@@ -14,17 +14,19 @@ module Leak
 		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
 
 			# @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 @@ def to_json(...)
 				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,47 @@ def remove(process_id)
 			# 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)
+				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 +109,7 @@ def check!(&block)
 				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

lib/memory/leak/monitor.rb

@@ -7,48 +7,50 @@
 
 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 +62,80 @@ def to_json(...)
 			# @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
+			
+			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

lib/memory/leak/system.rb

@@ -29,6 +29,26 @@ def self.total_memory_size
 					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

test/memory/leak/cluster.rb

@@ -17,14 +17,14 @@
 		before do
 			@children = 3.times.map do
 				child = Memory::Leak::LeakingChild.new
-				monitor = cluster.add(child.process_id, limit: 10)
+				monitor = cluster.add(child.process_id, increase_limit: 10)
 
 				[child.process_id, child]
 			end.to_h
 		end
 
 		after do
-			@children.each_value do |child|
+			@children&.each_value do |child|
 				child.close
 			end
 		end
@@ -37,7 +37,7 @@
 
 			# Force the first child to trigger the memory leak:
 			until monitor.leaking?
-				child.write_message(action: "allocate", size: monitor.threshold + 1)
+				child.write_message(action: "allocate", size: monitor.threshold_size + 1)
 				child.wait_for_message("allocated")
 
 				# Capture a sample of the memory usage:
@@ -46,7 +46,7 @@
 
 			cluster.check! do |process_id, monitor|
 				expect(process_id).to be == child.process_id
-				expect(monitor.count).to be == monitor.limit
+				expect(monitor.increase_count).to be == monitor.increase_limit
 				expect(monitor).to be(:leaking?)
 
 				child.close
@@ -63,35 +63,33 @@
 
 		it "can apply memory limit" do
 			# 100 MiB limit:
-			cluster.limit = 1024*1024*100
+			cluster.total_size_limit = 1024*1024*100
 
 			big_child = children.values.first
 			big_monitor = cluster.processes[big_child.process_id]
 			small_child = children.values.last
 			small_monitor = cluster.processes[small_child.process_id]
 
-			big_allocation = (cluster.limit * 0.8).floor - big_monitor.current
+			big_allocation = (cluster.total_size_limit * 0.8).floor - big_monitor.current_size
 			if big_allocation > 0
 				big_child.write_message(action: "allocate", size: big_allocation)
 				big_child.wait_for_message("allocated")
 			end
 
-			small_allocation = (cluster.limit * 0.2).floor - small_monitor.current
+			small_allocation = (cluster.total_size_limit * 0.2).floor - small_monitor.current_size
 			if small_allocation > 0
 				small_child.write_message(action: "allocate", size: small_allocation)
 				small_child.wait_for_message("allocated")
 			end
 
 			# The total memory usage is 110% of the limit, so the biggest child should be terminated:
-			cluster.check! do |process_id, monitor, total|
+			cluster.check! do |process_id, monitor, total_size|
 				expect(process_id).to be == big_child.process_id
 				expect(monitor).not.to be(:leaking?)
 
 				big_child.close
 				children.delete(process_id)
 				cluster.remove(process_id)
-				
-				true
 			end
 
 			expect_console.to have_logged(