memory-leak 0.9.2 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 127eb4efe2387664701cb1d56ba80dea1f0d833b92c645666b0bc8ad810851d7
-  data.tar.gz: 72360bbde481a84283a54edfa5cfede10522c0610be43c2d12b8ed0c36c9f5b1
+  metadata.gz: 4ef67abb16c59a1a7520e6d36db4bc8f86502efced42a96ec357f9700f1e7f39
+  data.tar.gz: 8d1f9ab5b22aeb8b4593bbc4266cdd783891a2ab904c39a55df62f954cc50f66
 SHA512:
-  metadata.gz: 56cf37bd97c28753a9e40898eeacee679617a175f38aa7f2be3dc850b2c669c463c4ce92e1027b865e274154cbecf5038c5f0cc916296eee9ed4b240cbf59c8b
-  data.tar.gz: 8611335101e758f763c564536573d717ab2c3670ffe13fb1dbe39218f196bc3a49a3e468d7495a057d2c11948867e58fa53af54f15e1f096de0418801963b37c
+  metadata.gz: 8b2a09ce8b4fd83fb60e69af8fe324d86309efd67dde443d8e18ecf6743393719ad9155e980b1cc079091764ca0e3d393bf23c104d7680209b40c9022ba4245b
+  data.tar.gz: b175f60ddd2f541689226955bd4711779cade944a342023bea0ff97cdbcd37d1e767ec1036d895ff8279de95feb256d21badf2d357f952cd7a2430f7a00ae33b

data/lib/memory/leak/cluster.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "console"
 require "process/metrics/host/memory"
@@ -11,14 +11,26 @@ 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.
+		# This class is used to manage a cluster of processes and detect memory leaks in each process.
+		# It can also enforce cluster-wide memory limits in two ways:
+		# 
+		# 1. **Total Size Limit** (`total_size_limit`): Limits the total memory used by all processes
+		#    in the cluster, calculated as max(shared memory) + sum(private memory).
+		# 
+		# 2. **Free Size Minimum** (`free_size_minimum`): Ensures the host system maintains a minimum
+		#    amount of free memory by terminating processes when free memory drops too low.
+		#
+		# Both limits can be active simultaneously. Processes are terminated in order of largest
+		# private memory first to maximize the impact of each termination.
 		class Cluster
 			# Create a new cluster.
 			#
 			# @parameter total_size_limit [Numeric | Nil] The total memory limit for the cluster.
-			def initialize(total_size_limit: nil)
+			# @parameter free_size_minimum [Numeric | Nil] The minimum free memory required on the host, in bytes.
+			def initialize(total_size_limit: nil, free_size_minimum: nil)
 				@total_size = nil
 				@total_size_limit = total_size_limit
+				@free_size_minimum = free_size_minimum
 				
 				@processes = {}
 			end
@@ -28,6 +40,7 @@ module Memory
 				{
 					total_size: @total_size,
 					total_size_limit: @total_size_limit,
+					free_size_minimum: @free_size_minimum,
 					processes: @processes.transform_values(&:as_json),
 				}
 			end
@@ -43,6 +56,9 @@ module Memory
 			# @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 [Numeric | Nil] The minimum free memory required on the host, in bytes. If free memory falls below this minimum, the cluster will terminate processes.
+			attr_accessor :free_size_minimum
+			
 			# @attribute [Hash(Integer, Monitor)] The process IDs and monitors in the cluster.
 			attr :processes
 			
@@ -56,15 +72,32 @@ module Memory
 				@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.
+			# Enforce the total size memory limit on 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.
+			#
+			# This method terminates processes (largest private memory first) until the total cluster memory
+			# usage drops below the limit. Total cluster memory usage is calculated as:
+			# 
+			#   total_size = max(shared memory usages) + sum(private memory usages)
+			# 
+			# This accounts for shared memory being counted only once across all processes, as shared memory
+			# regions (e.g., loaded libraries) are mapped into multiple processes but only consume memory once.
+			# 
+			# The calculation uses the initially computed maximum shared size throughout the termination loop
+			# for performance, even though terminating processes might change which process has the maximum
+			# shared size. This approximation is acceptable for enforcement purposes.
 			#
-			# Total cluster memory usage is calculated as: max(shared memory usages) + sum(private memory usages)
-			# This accounts for shared memory being counted only once across all processes.
+			# Termination stops when `total_size <= total_size_limit`, where `total_size` is incrementally
+			# updated by subtracting each terminated process's private memory contribution.
 			#
+			# @parameter total_size_limit [Numeric] The maximum total memory allowed for the cluster, in bytes.
 			# @parameter block [Proc] Required block to handle process termination.
-			# @yields {|process_id, monitor, total_size| ...} each process ID and monitor in order of maximum memory usage, return true if it was terminated to adjust memory usage.
+			# @yields {|process_id, monitor, total_size| ...} each process ID and monitor in order of decreasing private memory size.
+			# 	@parameter process_id [Integer] The process ID to terminate.
+			# 	@parameter monitor [Monitor] The monitor for the process.
+			# 	@parameter total_size [Integer] The current estimated total cluster memory usage, in bytes. Updated incrementally after each termination.
 			# @raises [ArgumentError] if no block is provided.
-			protected def apply_limit!(total_size_limit = @total_size_limit, &block)
+			# @returns [Boolean] Returns true if processes were yielded for termination, false otherwise.
+			protected def enforce_total_size_limit!(total_size_limit = @total_size_limit, &block)
 				# Only processes with known private size can be considered:
 				monitors = @processes.values.select do |monitor|
 					monitor.current_private_size != nil
@@ -91,15 +124,16 @@ module Memory
 				
 				monitors.each do |monitor|
 					if @total_size > total_size_limit
-						# Capture values before yielding (process may be removed):
+						# Capture private size before yielding (process may be removed):
 						private_size = monitor.current_private_size
 						
 						yield(monitor.process_id, monitor, @total_size)
 						
-						# Incrementally update: subtract this process's contribution
+						# Incrementally update total size by subtracting this process's private memory contribution.
+						# We keep the previously computed maximum_shared_size for performance,
+						# even though the maximum may shift to a different process after termination.
 						sum_private_size -= private_size
 						
-						# We use the computed maximum shared size, even if it might not be correct, as it is good enough for enforcing the limits and recalculating it is non-trivial.
 						@total_size = maximum_shared_size + sum_private_size
 					else
 						break
@@ -107,6 +141,71 @@ module Memory
 				end
 			end
 			
+			# Enforce the minimum free memory requirement. If free memory falls below the minimum, yields each process ID and monitor in order of maximum memory usage, so that they could be terminated and/or removed.
+			#
+			# This method terminates processes (largest private memory first) until the estimated free memory
+			# rises above the minimum threshold. The free memory calculation is approximate:
+			# - Free memory is captured once at the start
+			# - Expected freed memory is estimated by summing terminated process private memory sizes
+			# - The OS may not immediately release all private memory to the free pool
+			# - Other system processes may allocate memory concurrently
+			#
+			# Termination stops when `free_memory + freed_private_size >= free_size_minimum`, where
+			# `freed_private_size` is the sum of private memory from all terminated processes.
+			#
+			# @parameter free_size_minimum [Numeric] The minimum free memory required, in bytes.
+			# @parameter block [Proc] Required block to handle process termination.
+			# @yields {|process_id, monitor, free_memory| ...} each process ID and monitor in order of decreasing private memory size.
+			# 	@parameter process_id [Integer] The process ID to terminate.
+			# 	@parameter monitor [Monitor] The monitor for the process.
+			# 	@parameter free_memory [Integer] The estimated current free memory (initial free + sum of freed private memory so far), in bytes. This is an estimate and may not reflect actual system state.
+			# @raises [ArgumentError] if no block is provided.
+			# @returns [Boolean] Returns true if processes were yielded for termination, false otherwise.
+			protected def enforce_free_size_minimum!(free_size_minimum = @free_size_minimum, &block)
+				return false unless free_size_minimum
+				
+				host_memory = Process::Metrics::Host::Memory.capture
+				return false unless host_memory
+				
+				free_memory = host_memory.free_size
+				
+				if free_memory < free_size_minimum
+					Console.warn(self, "Free memory below minimum.", free_memory: free_memory, free_size_minimum: free_size_minimum, host_memory: host_memory)
+				else
+					Console.info(self, "Free memory above minimum.", free_memory: free_memory, free_size_minimum: free_size_minimum, host_memory: host_memory)
+					return false
+				end
+				
+				# Only processes with known private size can be considered:
+				monitors = @processes.values.select do |monitor|
+					monitor.current_private_size != nil
+				end
+				
+				# Sort by private memory size (descending) to terminate largest processes first:
+				monitors.sort_by! do |monitor|
+					-monitor.current_private_size
+				end
+				
+				# Track how much private memory we've freed by terminating processes.
+				# Note: This is an estimate based on process private memory sizes.
+				# Actual free memory may differ due to OS memory management and other processes.
+				freed_private_size = 0
+				
+				monitors.each do |monitor|
+					if free_memory + freed_private_size < free_size_minimum
+						# Capture private size before yielding (process may be removed):
+						private_size = monitor.current_private_size
+						
+						yield(monitor.process_id, monitor, free_memory + freed_private_size)
+						
+						# Incrementally track freed memory:
+						freed_private_size += private_size
+					else
+						break
+					end
+				end
+			end
+			
 			# Sample the memory usage of all processes in the cluster.
 			def sample!
 				@processes.each_value(&:sample!)
@@ -131,9 +230,14 @@ module Memory
 				if block_given?
 					leaking.each(&block)
 					
-					# Finally, apply any per-cluster memory limits:
+					# Finally, enforce any per-cluster memory limits:
 					if @total_size_limit
-						apply_limit!(@total_size_limit, &block)
+						enforce_total_size_limit!(@total_size_limit, &block)
+					end
+					
+					# Enforce minimum free memory requirement:
+					if @free_size_minimum
+						enforce_free_size_minimum!(@free_size_minimum, &block)
 					end
 				end
 				

data/lib/memory/leak/monitor.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "console"
 require "process/metrics/memory"

data/lib/memory/leak/version.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 module Memory
 	module Leak
-		VERSION = "0.9.2"
+		VERSION = "0.10.0"
 	end
 end

data/readme.md

@@ -8,10 +8,16 @@ Detects memory leaks in Ruby applications.
 
 Please see the [project documentation](https://socketry.github.io/memory-leak/) for more details.
 
+  - [Getting Started](https://socketry.github.io/memory-leak/guides/getting-started/index) - This guide explains how to use `memory-leak` to detect and prevent memory leaks in your Ruby applications.
+
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/memory-leak/releases/index) for all releases.
 
+### v0.10.0
+
+  - Introduce `free_size_minimum` to monitor minimum free memory size, which can be used to trigger alerts or actions when available memory is critically low.
+
 ### v0.9.2
 
   - Also log host memory in total memory usage logs.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.10.0
+
+  - Introduce `free_size_minimum` to monitor minimum free memory size, which can be used to trigger alerts or actions when available memory is critically low.
+
 ## v0.9.2
 
   - Also log host memory in total memory usage logs.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memory-leak
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.10.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -42,16 +42,16 @@ dependencies:
   name: process-metrics
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: 0.10.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: 0.10.1
 executables: []
 extensions: []
 extra_rdoc_files: []

metadata.gz.sig

@@ -1,2 +1,2 @@
-@	�<}f7X����[�H��]� 1�3-�j�w�3Y���'�z��i�ي�H�/f��P�����9�|��x�����(�"�Y����7"�5$w:S/����)d-���K�_
��ߟ���Z�����wq�0�
-BJ
+[+|�1���҂�X|�͖�wx�t���}d�i��B���z���f�2�4tk�3��B��LR���hy��+%;^Mo}b�$`PG�ʸq���9�f���+l~7������ι�����6#���`�L;y�_��61vv��&`����M�Y?���E����7G�4��Ή4�r��?�L-���c��!��+=O��@�`%�7�w
+��l����KM%5B,�Y��=P�>/�1��I�>l0��f��w���+%��W8