Introduce Memory::Usage and remove RSpec integration.

Author: samuel-williams-shopify

lib/memory/aggregate.rb

@@ -3,68 +3,21 @@
 # Released under the MIT License.
 # Copyright, 2020-2025, by Samuel Williams.
 
+require_relative "usage"
+
 module Memory
-	UNITS = {
-		0 => "B",
-		3 => "KiB",
-		6 => "MiB",
-		9 => "GiB",
-		12 => "TiB",
-		15 => "PiB",
-		18 => "EiB",
-		21 => "ZiB",
-		24 => "YiB"
-	}.freeze
-	
-	# Format bytes into human-readable units.
-	# @parameter bytes [Integer] The number of bytes to format.
-	# @returns [String] Formatted string with appropriate unit (e.g., "1.50 MiB").
-	def self.formatted_bytes(bytes)
-		return "0 B" if bytes.zero?
-		
-		scale = Math.log2(bytes).div(10) * 3
-		scale = 24 if scale > 24
-		"%.2f #{UNITS[scale]}" % (bytes / 10.0**scale)
-	end
-	
 	# Aggregates memory allocations by a given metric.
 	# Groups allocations and tracks totals for memory usage and allocation counts.
 	class Aggregate
-		Total = Struct.new(:memory, :count) do
-			def initialize
-				super(0, 0)
-			end
-			
-			def << allocation
-				self.memory += allocation.memsize
-				self.count += 1
-			end
-			
-			def formatted_memory
-				self.memory
-			end
-			
-			def to_s
-				"(#{Memory.formatted_bytes memory} in #{count} allocations)"
-			end
-			
-			def as_json(options = nil)
-				{
-					memory: memory,
-					count: count
-				}
-			end
-		end
-		
 		# Initialize a new aggregate with a title and metric block.
 		# @parameter title [String] The title for this aggregate.
 		# @parameter block [Block] A block that extracts the metric from an allocation.
 		def initialize(title, &block)
 			@title = title
 			@metric = block
 
-			@total = Total.new
-			@totals = Hash.new{|h,k| h[k] = Total.new}
+			@total = Usage.new
+			@totals = Hash.new{|h,k| h[k] = Usage.new}
 		end
 
 		attr :title
@@ -78,11 +31,8 @@ def << allocation
 			metric = @metric.call(allocation)
 			total = @totals[metric]
 
-			total.memory += allocation.memsize
-			total.count += 1
-			
-			@total.memory += allocation.memsize
-			@total.count += 1
+			total << allocation
+			@total << allocation
 		end
 
 		# Sort totals by a given key.

lib/memory/format.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Memory
+	UNITS = {
+		0 => "B",
+		3 => "KiB",
+		6 => "MiB",
+		9 => "GiB",
+		12 => "TiB",
+		15 => "PiB",
+		18 => "EiB",
+		21 => "ZiB",
+		24 => "YiB"
+	}.freeze
+	
+	# Format bytes into human-readable units.
+	# @parameter bytes [Integer] The number of bytes to format.
+	# @returns [String] Formatted string with appropriate unit (e.g., "1.50 MiB").
+	def self.formatted_bytes(bytes)
+		return "0 B" if bytes.zero?
+		
+		scale = Math.log2(bytes).div(10) * 3
+		scale = 24 if scale > 24
+		"%.2f #{UNITS[scale]}" % (bytes / 10.0**scale)
+	end
+end

lib/memory/report.rb

@@ -29,8 +29,8 @@ def self.general(**options)
 		def initialize(aggregates, retained_only: true)
 			@retained_only = retained_only
 
-			@total_allocated = Aggregate::Total.new
-			@total_retained = Aggregate::Total.new
+			@total_allocated = Usage.new
+			@total_retained = Usage.new
 
 			@aggregates = aggregates
 		end

lib/memory/rspec/profiler.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "format"
+
+require "set"
+require "objspace"
+
+module Memory
+	class Usage
+		def initialize(size = 0, count = 0)
+			@size = size
+			@count = count
+		end
+		
+		# @attribute size [Integer] The total size of the usage in bytes.
+		attr_accessor :size
+		
+		alias memsize size
+		
+		# @attribute count [Integer] The total count of the usage in object instances.
+		attr_accessor :count
+		
+		# Add an allocation to this usage.
+		# @parameter allocation [Allocation] The allocation to add.
+		def << allocation
+			self.size += allocation.memsize
+			self.count += 1
+			
+			return self
+		end
+		
+		# Compute the usage of an object and all reachable objects from it.
+		# @parameter root [Object] The root object to start traversal from.
+		# @returns [Usage] The usage of the object and all reachable objects from it.
+		def self.of(root)
+			seen = Set.new.compare_by_identity
+			
+			count = 0
+			size = 0
+			
+			queue = [root]
+			while queue.any?
+				object = queue.shift
+				# Skip modules and symbols, they are usually "global":
+				next if object.is_a?(Module)
+				# Note that `reachable_objects_from` does not include symbols, numbers, or other value types, AFAICT.
+				
+				# Skip objects we have already seen:
+				next if seen.include?(object)
+				
+				# Add the object to the seen set and update the count and size:
+				seen.add(object)
+				count += 1
+				size += ObjectSpace.memsize_of(object)
+				
+				# Add the object's reachable objects to the queue:
+				queue.concat(ObjectSpace.reachable_objects_from(object))
+			end
+			
+			return new(size, count)
+		end
+		
+		def as_json(...)
+			{
+				size: @size,
+				count: @count
+			}
+		end
+		
+		def to_json(...)
+			as_json.to_json(...)
+		end
+		
+		def to_s
+			"(#{Memory.formatted_bytes(memory)} in #{count} allocations)"
+		end
+	end
+end

lib/memory/usage.rb

@@ -1,5 +1,10 @@
 # Releases
 
+## Unreleased
+
+  - Removed old `RSpec` integration.
+  - Introduced `Memory::Usage` and `Memory::Usage.of(object)` which recursively computes memory usage of an object and its contents.
+
 ## v0.7.1
 
   - Ensure aggregate keys are safe for serialization (and printing).

releases.md

@@ -27,12 +27,12 @@
 		)
 
 		expect(result[:total_allocated]).to have_keys(
-			memory: be_a(Integer),
+			size: be_a(Integer),
 			count: be_a(Integer),
 		)
 
 		expect(result[:total_retained]).to have_keys(
-			memory: be_a(Integer),
+			size: be_a(Integer),
 			count: be_a(Integer),
 		)