memory-leak 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b50558351a2324cdddac0369f5b4f81d8787a1b9cee2d92206c997777637ae4
-  data.tar.gz: 7091170b19d36840768f145dbba9bd8f805724af1a2332b60f8ac3df40bb5ed3
+  metadata.gz: 9c289492ac6aa4dc49416b15d859f629fbf1f0cc234d0f1969c0f0fc9e362607
+  data.tar.gz: 23f0b4b50772e92d5a90d89510a9929eb0889c050b45cf864084061e11307fe8
 SHA512:
-  metadata.gz: 4edd0b28026f560e48717721f7f6afcb10798710654758637320ed8dabcd6af8306d68f69d825ab901c78eca027e1172e54e1c970204f2cc7a5e5ac8a0686d0b
-  data.tar.gz: 959f65bc8f7e403cd482d0519d1768e5226b0ed95995dc52a0dca3c9fbc03893e9df7a54b4ad32b49273e1d3919911d93c8965d5e5927157b67c06b80c8da99d
+  metadata.gz: 796f477f191c517e8e46cd2889ae04501fe81912c45190ecaa9ea2b0e61f70c621cc84668c3429a32fa221aecb8c64c42ea48d8b0a16c16a9d243f82a02fe4e4
+  data.tar.gz: 40ff9dbe71d8b6a063295a2ce622961d2fb85c2149c51a8ebcf682ef80e276e0edfa148154ea460cc03f82c06c7de1c63d9b5ff1b70f17a65b2f88c99cfa16c2

checksums.yaml.gz.sig

@@ -1,4 +1 @@
-eiM�zK�a�d��]<,�k��.-WZ8V����v*����]/|�P��dž��F��T�y�� ���J�B˰
-Q+�:��9�a�����#~x����W�����'�Ӧp��H4��V�#=��d,���$���ۨ�<hjN��<�aó����Gk�O��5�[4���{��
-��p�(l�%5��X����l���z�>��iKv�L�uF{{b�L�+[���
-�
háD������Ǽ�,��4�D�1~��H�u8�=��V��������z������l	�'���}��;�]�\��d�'(,� �]�%�\/5+��ڜ���	����}塥H_��6����Ra0J������1e!�1*��&�PK���`��g^9��
+K��W�mQ�����PF��0�0=EA�G%�P��i���Ӑ��@
���:�*?b��wRok�{��|gv^+9,0�/�>s��{��0r]Is�����Y��TU���(�� �3�Wt�=)�2/#9sU���\��v,�T)��h��BQͽ��t���'ZJg�(!��Å>_X�NO�2V2q^6�57M����o�J��Y`�F5ꑍ�M��ܨ�3SB����*�Je���gJҺ{>�z�1;��!=��3�,^y�ǀ'ۭWV�,�$=���1Aq��Y��i����Mo��2o[W�Z��@�����VL�ЇDb?�Aq��+2�r�@a�`�u��m6�9mz��Rlf��43���?��+Zw�x*��j����`X
�>��5�#�/�wf��

data/lib/memory/leak/cluster.rb

@@ -0,0 +1,88 @@
+# 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
+				
+				@pids = {}
+			end
+			
+			# @attribute [Numeric | Nil] The memory limit for the cluster.
+			attr_accessor :limit
+			
+			# @attribute [Hash(PID, Monitor)] The process IDs and monitors in the cluster.
+			attr :pids
+			
+			# Add a new process ID to the cluster.
+			def add(pid, **options)
+				@pids[pid] = Monitor.new(pid, **options)
+			end
+			
+			# Remove a process ID from the cluster.
+			def remove(pid)
+				@pids.delete(pid)
+			end
+			
+			# Apply the memory limit to the cluster. If the total memory usage exceeds the limit, yields each PID and monitor in order of maximum memory usage, so that they could be terminated and/or removed.
+			#
+			# @yields {|pid, 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 = @pids.values.map(&:current).sum
+				
+				if total > limit
+					Console.warn(self, "Total memory usage exceeded limit.", total: total, limit: limit)
+				end
+				
+				sorted = @pids.sort_by do |pid, monitor|
+					-monitor.current
+				end
+				
+				sorted.each do |pid, monitor|
+					if total > limit
+						if yield pid, monitor, total
+							total -= monitor.current
+						end
+					else
+						break
+					end
+				end
+			end
+			
+			# Check all processes in the cluster for memory leaks.
+			#
+			# @yields {|pid, monitor| ...} each process ID and monitor that is leaking or exceeds the memory limit.
+			def check!(&block)
+				leaking = []
+				
+				@pids.each do |pid, monitor|
+					monitor.sample!
+					
+					if monitor.leaking?
+						Console.debug(self, "Memory Leak Detected!", pid: pid, monitor: monitor)
+						
+						leaking << [pid, 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,7 +12,7 @@ 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
+		class Monitor
 			# We only track heap size changes greater than this threshold (KB), across the DEFAULT_INTERVAL.
 			# True memory leaks will eventually hit this threshold, while small fluctuations will not.
 			DEFAULT_THRESHOLD = 1024*10
@@ -22,22 +22,27 @@ module Memory
 			# 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 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)
+			def initialize(pid = Process.pid, maximum: nil, threshold: DEFAULT_THRESHOLD, limit: DEFAULT_LIMIT)
+				@pid = pid
+				
 				@maximum = maximum
 				@threshold = threshold
 				@limit = limit
-				@pid = pid
 				
 				# The number of increasing heap size samples.
 				@count = 0
+				@current = nil
 			end
 			
+			# @attribute [Integer] The process ID to monitor.
+			attr :pid
+			
 			# @attribute [Numeric] The current maximum heap size.
 			attr :maximum
 			
@@ -55,43 +60,48 @@ 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|
+			private def memory_usage
+				IO.popen(["ps", "-o", "rss=", @pid.to_s]) do |io|
 					return Integer(io.readlines.last)
 				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.2.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.2.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -43,7 +43,8 @@ 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: []