memory 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 266bdfec74c35392a9c086c366df9bb6ab4fb5e1b162b98d3757f690fff09ded
-  data.tar.gz: dffe8472314144b5786b5c445c6e01973114e9c3915d08aae0352fc1be76d329
+  metadata.gz: e3be5bbd2ea825e556faa064af09cfd77043d7ca04cc2767d7dffe9efa877b4b
+  data.tar.gz: 286b7693641ebf10c643e03baeb678dfa4e4135c4cd3b709b20b2dc608a61edd
 SHA512:
-  metadata.gz: 4dcf3e65b4a7dee68b55919dc44004149a6febe80fde00d539d2b0361eea62dd47ab742006ef7ed75a2980829f0f58cbf1c341098ae394ac4ac3b7a4d816752b
-  data.tar.gz: '038621f8d88603eb8b0b2a89fe13e4007bc100ce0c16c53febd9d02a6cf4fa3a00c6c3e967bfa8a6aa6507e3611266cae774dc016d330fe5b22d5322beee12e3'
+  metadata.gz: 2eddc8c03c592d5ef1a898af3b8fb72e71ed526473ad70cb74f4c905080be35c1d50ac3271e05da292e390e900a25fafe85a996d6f18b89016ca731d1f84ba4d
+  data.tar.gz: 535bcded6a5eb23536443d729c0a27034898b8240805b4d2180f9b18185d788b13572f9f73671be76fd47af50b6277659f9f5305ebba7a235d2440c595d6acf5

data/lib/memory/aggregate.rb

@@ -3,59 +3,12 @@
 # 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.
@@ -63,8 +16,8 @@ module Memory
 			@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 @@ module Memory
 			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.
@@ -129,7 +79,7 @@ module Memory
 			@title = title
 			@metric = block
 			
-			@aggregates = Hash.new{|h,k| h[k] = Aggregate.new(k.inspect, &@metric)}
+			@aggregates = Hash.new{|h,k| h[k] = Aggregate.new(safe_key(k.inspect), &@metric)}
 		end
 		
 		attr :title
@@ -169,10 +119,14 @@ module Memory
 		# @parameter options [Hash | Nil] Optional JSON serialization options.
 		# @returns [Hash] JSON-compatible representation.
 		def as_json(options = nil)
-			{
+			result = {
 				title: @title,
-				aggregates: @aggregates.map{|k, v| [k, v.as_json]}
+				aggregates: @aggregates.map{|k, v| [safe_key(k), v.as_json]}
 			}
 		end
+		
+		private def safe_key(key)
+			key.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+		end
 	end
 end

data/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

data/lib/memory/report.rb

@@ -29,8 +29,8 @@ module Memory
 		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

data/lib/memory/usage.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

data/lib/memory/version.rb

@@ -7,5 +7,5 @@
 # Copyright, 2020-2025, by Samuel Williams.
 
 module Memory
-	VERSION = "0.7.0"
+	VERSION = "0.8.0"
 end

data/readme.md

@@ -94,6 +94,15 @@ end
 
 Please see the [project releases](https://socketry.github.io/memory/releases/index) for all releases.
 
+### v0.8.0
+
+  - 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).
+
 ### v0.7.0
 
   - Add `Memory::Sampler#as_json` and `#to_json`.

data/releases.md

@@ -1,5 +1,14 @@
 # Releases
 
+## v0.8.0
+
+  - 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).
+
 ## v0.7.0
 
   - Add `Memory::Sampler#as_json` and `#to_json`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memory
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Sam Saffron
@@ -116,9 +116,10 @@ files:
 - lib/memory/aggregate.rb
 - lib/memory/cache.rb
 - lib/memory/deque.rb
+- lib/memory/format.rb
 - lib/memory/report.rb
-- lib/memory/rspec/profiler.rb
 - lib/memory/sampler.rb
+- lib/memory/usage.rb
 - lib/memory/version.rb
 - license.md
 - readme.md

data/lib/memory/rspec/profiler.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
-
-require_relative "../sampler"
-
-module Memory
-	# @namespace
-	module RSpec
-		# Integration with RSpec for memory profiling test suites.
-		# Profiles memory allocations for RSpec example groups and generates reports.
-		module Profiler
-			# Profile memory allocations for RSpec examples.
-			# @parameter scope [Object] The RSpec scope to apply profiling hooks to.
-			def self.profile(scope)
-				memory_sampler = nil
-				
-				scope.before(:all) do |example_group|
-					name = example_group.class.description.gsub(/[^\w]+/, "-")
-					path = "#{name}.mprof"
-					
-					skip if File.exist?(path)
-					
-					memory_sampler = Memory::Sampler.new
-					memory_sampler.start
-				end
-				
-				scope.after(:all) do |example_group|
-					name = example_group.class.description.gsub(/[^\w]+/, "-")
-					path = "#{name}.mprof"
-					
-					if memory_sampler
-						memory_sampler.stop
-						
-						File.open(path, "w", encoding: Encoding::BINARY) do |io|
-							memory_sampler.dump(io)
-						end
-						
-						memory_sampler = nil
-					end
-				end
-				
-				scope.after(:suite) do
-					memory_sampler = Memory::Sampler.new
-					
-					Dir.glob("*.mprof") do |path|
-						memory_sampler.load(File.read(
-							path,
-							encoding: Encoding::BINARY,
-						))
-					end
-					
-					memory_sampler.report.print
-				end
-			end
-		end
-	end
-end