memory-leak 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b50558351a2324cdddac0369f5b4f81d8787a1b9cee2d92206c997777637ae4
-  data.tar.gz: 7091170b19d36840768f145dbba9bd8f805724af1a2332b60f8ac3df40bb5ed3
+  metadata.gz: 426ae960c62375c639420dcf7f498e9e5226b1519614b1fff452b2212f70d7fe
+  data.tar.gz: 6002732a1fb1e17fc105ca6528a510e3d0f564827ff7197682286e68f98a0da9
 SHA512:
-  metadata.gz: 4edd0b28026f560e48717721f7f6afcb10798710654758637320ed8dabcd6af8306d68f69d825ab901c78eca027e1172e54e1c970204f2cc7a5e5ac8a0686d0b
-  data.tar.gz: 959f65bc8f7e403cd482d0519d1768e5226b0ed95995dc52a0dca3c9fbc03893e9df7a54b4ad32b49273e1d3919911d93c8965d5e5927157b67c06b80c8da99d
+  metadata.gz: f36940083fb9907c227bff8242af9ec35a64951f9621b8581adce24cfbb8b2510c7810415d04125e201b36838a06775d9204a6dfc953c780134dec2115924f6d
+  data.tar.gz: 4e727229e8b12a4c73b88066c423f4683a3e9b21fe29c42214eab422c6e310463dc71152c539d5f6cd302e08b9f0ecc3e7166e7620d031c543d90483a3f7e134

data/lib/memory/leak/cluster.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "console"
+require_relative "monitor"
+
+module Memory
+	module Leak
+		# Detects memory leaks in a cluster of processes.
+		#
+		# This class is used to manage a cluster of processes and detect memory leaks in each process. It can also apply a memory limit to the cluster, and terminate processes if the memory limit is exceeded.
+		class Cluster
+			# Create a new cluster.
+			#
+			# @parameter limit [Numeric | Nil] The (total) memory limit for the cluster.
+			def initialize(limit: nil)
+				@limit = limit
+				
+				@processes = {}
+			end
+			
+			# @returns [Hash] A serializable representation of the cluster.
+			def as_json(...)
+				{
+					limit: @limit,
+					processes: @processes.transform_values(&:as_json),
+				}
+			end
+			
+			# @returns [String] The JSON representation of the cluster.
+			def to_json(...)
+				as_json.to_json(...)
+			end
+			
+			# @attribute [Numeric | Nil] The memory limit for the cluster.
+			attr_accessor :limit
+			
+			# @attribute [Hash(Integer, Monitor)] The process IDs and monitors in the cluster.
+			attr :processes
+			
+			# Add a new process ID to the cluster.
+			def add(process_id, **options)
+				@processes[process_id] = Monitor.new(process_id, **options)
+			end
+			
+			# Remove a process ID from the cluster.
+			def remove(process_id)
+				@processes.delete(process_id)
+			end
+			
+			# 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
+				
+				if total > limit
+					Console.warn(self, "Total memory usage exceeded limit.", total: total, limit: limit)
+				end
+				
+				sorted = @processes.sort_by do |process_id, monitor|
+					-monitor.current
+				end
+				
+				sorted.each do |process_id, monitor|
+					if total > limit
+						if yield process_id, monitor, total
+							total -= monitor.current
+						end
+					else
+						break
+					end
+				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)
+				leaking = []
+				
+				@processes.each do |process_id, monitor|
+					monitor.sample!
+					
+					if monitor.leaking?
+						Console.debug(self, "Memory Leak Detected!", process_id: process_id, monitor: monitor)
+						
+						leaking << [process_id, monitor]
+					end
+				end
+				
+				leaking.each(&block)
+				
+				# Finally, apply any per-cluster memory limits:
+				apply_limit!(@limit, &block) if @limit
+			end
+		end
+	end
+end

data/lib/memory/leak/{detector.rb → monitor.rb}

@@ -12,32 +12,54 @@ module Memory
 		# 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 Detector
-			# We only track heap size changes greater than this threshold (KB), across the DEFAULT_INTERVAL.
+		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*10
+			DEFAULT_THRESHOLD = 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
 			
-			# Create a new detector.
+			# Create a new monitor.
 			#
-			# @parameter maximum [Numeric] The initial maximum heap size, from which we willl track increases, in KiB.
-			# @parameter threshold [Numeric] The threshold for heap size increases, in KiB.
+			# @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.
-			# @pid [Integer] The process ID to monitor.
-			def initialize(maximum: nil, threshold: DEFAULT_THRESHOLD, limit: DEFAULT_LIMIT, pid: Process.pid)
+			# @parameter [Integer] The process ID to monitor.
+			def initialize(process_id = Process.pid, maximum: nil, threshold: DEFAULT_THRESHOLD, limit: DEFAULT_LIMIT)
+				@process_id = process_id
+				
 				@maximum = maximum
 				@threshold = threshold
 				@limit = limit
-				@pid = pid
 				
 				# The number of increasing heap size samples.
 				@count = 0
+				@current = nil
+			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,
+				}
+			end
+			
+			# @returns [String] The JSON representation of the cluster.
+			def to_json(...)
+				as_json.to_json(...)
 			end
 			
+			# @attribute [Integer] The process ID to monitor.
+			attr :process_id
+			
 			# @attribute [Numeric] The current maximum heap size.
 			attr :maximum
 			
@@ -54,44 +76,49 @@ module Memory
 			#
 			# 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 KiB.
-			def memory_usage(pid = @pid)
-				IO.popen(["ps", "-o", "rss=", pid.to_s]) do |io|
-					return Integer(io.readlines.last)
+			# @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
 			end
 			
+			# @returns [Integer] The last sampled memory usage.
+			def current
+				@current ||= memory_usage
+			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.
 			#
 			# @returns [Boolean] True if a memory leak has been detected.
-			def memory_leak_detected?
+			def leaking?
 				@count >= @limit
 			end
 			
 			# Capture a memory usage sample and yield if a memory leak is detected.
 			#
-			# @yields {|sample, detector| ...} If a memory leak is detected.
-			def capture_sample
-				sample = memory_usage
+			# @yields {|sample, monitor| ...} If a memory leak is detected.
+			def sample!
+				@current = memory_usage
 				
 				if @maximum
-					delta = sample - @maximum
-					Console.debug(self, "Heap size captured.", sample: sample, delta: delta, threshold: @threshold, maximum: @maximum)
+					delta = @current - @maximum
+					Console.debug(self, "Heap size captured.", current: @current, delta: delta, threshold: @threshold, maximum: @maximum)
 					
 					if delta > @threshold
-						@maximum = sample
+						@maximum = @current
 						@count += 1
 						
 						Console.debug(self, "Heap size increased.", maximum: @maximum, count: @count)
 					end
 				else
-					Console.debug(self, "Initial heap size captured.", sample: sample)
-					@maximum = sample
+					Console.debug(self, "Initial heap size captured.", current: @current)
+					@maximum = @current
 				end
 				
-				return sample
+				return @current
 			end
 		end
 	end

data/lib/memory/leak/version.rb

@@ -5,6 +5,6 @@
 
 module Memory
 	module Leak
-		VERSION = "0.1.0"
+		VERSION = "0.3.0"
 	end
 end

data/lib/memory/leak.rb

@@ -4,7 +4,7 @@
 # Copyright, 2025, by Samuel Williams.
 
 require_relative "leak/version"
-require_relative "leak/detector"
+require_relative "leak/monitor"
 
 # @namespace
 module Memory

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memory-leak
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -36,14 +36,15 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-02-24 00:00:00.000000000 Z
+date: 2025-02-26 00:00:00.000000000 Z
 dependencies: []
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - lib/memory/leak.rb
-- lib/memory/leak/detector.rb
+- lib/memory/leak/cluster.rb
+- lib/memory/leak/monitor.rb
 - lib/memory/leak/version.rb
 - license.md
 - readme.md
@@ -70,5 +71,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.2
 specification_version: 4
-summary: A memory leak detector.
+summary: A memory leak monitor.
 test_files: []