memory 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 535ecdd0c6181d94b31384e4f71b4b4ce52d499d43daa647120fb22cf3dc244b
-  data.tar.gz: bfc66be86d65f7065ebc6a4193420ccbe50a98ad5e581ba6cf613484d1846012
+  metadata.gz: 610a559d7ecf64e0ec26f443e53492bcc8853f4c2a384ccb4384bf14855b9805
+  data.tar.gz: 53c34a593cf01eb64661d762b46a5a1e2d0b4ef3597f399cf6c2be76244ad2d4
 SHA512:
-  metadata.gz: e2df82be2210853cdc3ede7d47d450d1a38bc14291ee4fdaa3bece83809ce78ffb73ae714d52da9843dbd43d2659e6a97b17005ecbf3abe1f81fe8a687b0cbc5
-  data.tar.gz: de6c8972b60a489e7f62834fe926674ed55103fae47a401ef81674b43a8a79b271a8b21051948c56b094a0372abb5493c78739265686b4c4591272ffd70b8f4b
+  metadata.gz: 3d014fe210c6b215773e275a7b9caa1ddcf346dae6fb21e06c637d01b638ff193154b77e3e4b54a6f9fca7a92bb9d18a8d56bf75ea0cc057d2749fe6b75b5d47
+  data.tar.gz: 7918321809f910e3979384a44863e02f6c37e797918caf6e1524103e4a808be847a2bec37ddc1a1cbf35e761e45c15aef2fb4f85d521828ae252e0a5042660d5

data/lib/memory/graph.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "set"
+
+module Memory
+	# Tracks object traversal paths for memory analysis.
+	#
+	# The Graph class maintains a mapping of objects to their parent objects,
+	# allowing you to trace the reference path from any object back to its root.
+	class Graph
+		def initialize
+			@mapping = Hash.new.compare_by_identity
+		end
+		
+		# The internal mapping of objects to their parents.
+		attr_reader :mapping
+		
+		# Add a parent-child relationship to the via mapping.
+		#
+		# @parameter child [Object] The child object.
+		# @parameter parent [Object] The parent object that references the child.
+		def []=(child, parent)
+			@mapping[child] = parent
+		end
+		
+		# Get the parent of an object.
+		#
+		# @parameter child [Object] The child object.
+		# @returns [Object | Nil] The parent object, or nil if not tracked.
+		def [](child)
+			@mapping[child]
+		end
+		
+		# Check if an object is tracked in the via mapping.
+		#
+		# @parameter object [Object] The object to check.
+		# @returns [Boolean] True if the object is tracked.
+		def key?(object)
+			@mapping.key?(object)
+		end
+		
+		# Find how a parent object references a child object.
+		#
+		# @parameter parent [Object] The parent object.
+		# @parameter child [Object] The child object to find.
+		# @returns [String | Nil] A human-readable description of the reference, or nil if not found.
+		def find_reference(parent, child)
+			# Check instance variables:
+			parent.instance_variables.each do |ivar|
+				value = parent.instance_variable_get(ivar)
+				if value.equal?(child)
+					return ivar.to_s
+				end
+			end
+			
+			# Check array elements:
+			if parent.is_a?(Array)
+				parent.each_with_index do |element, index|
+					if element.equal?(child)
+						return "[#{index}]"
+					end
+				end
+			end
+			
+			# Check hash keys and values:
+			if parent.is_a?(Hash)
+				parent.each do |key, value|
+					if value.equal?(child)
+						return "[#{key.inspect}]"
+					end
+					if key.equal?(child)
+						return "(key: #{key.inspect})"
+					end
+				end
+			end
+			
+			# Check struct members:
+			if parent.is_a?(Struct)
+				parent.each_pair do |member, value|
+					if value.equal?(child)
+						return ".#{member}"
+					end
+				end
+			end
+			
+			# Could not determine the reference:
+			return nil
+		end
+		
+		# Construct a human-readable path from an object back to a root.
+		#
+		# @parameter object [Object] The object to trace back from.
+		# @parameter root [Object | Nil] The root object to trace to. If nil, traces to any root.
+		# @returns [Array(Array(Object), Array(String))] A tuple of [object_path, reference_path].
+		def path_to(object, root = nil)
+			# Build the object path by following via backwards:
+			object_path = [object]
+			current = object
+			
+			while @mapping.key?(current)
+				parent = @mapping[current]
+				object_path << parent
+				current = parent
+				
+				# Stop if we reached the specified root:
+				break if root && current.equal?(root)
+			end
+			
+			# Reverse to get path from root to object:
+			object_path.reverse!
+			
+			return object_path
+		end
+		
+		# Format a human-readable path string.
+		#
+		# @parameter object [Object] The object to trace back from.
+		# @parameter root [Object | Nil] The root object to trace to. If nil, traces to any root.
+		# @returns [String] A formatted path string.
+		def path(object, root = nil)
+			object_path = path_to(object, root)
+			
+			# Start with the root object description:
+			parts = ["#<#{object_path.first.class}:0x%016x>" % (object_path.first.object_id << 1)]
+			
+			# Append each reference in the path:
+			(1...object_path.size).each do |i|
+				parent = object_path[i - 1]
+				child = object_path[i]
+				
+				parts << (find_reference(parent, child) || "<??>")
+			end
+			
+			return parts.join
+		end
+	end
+end
+

data/lib/memory/usage.rb

@@ -57,33 +57,42 @@ module Memory
 		]
 		
 		# Compute the usage of an object and all reachable objects from it.
+		#
+		# The root is always visited even if it is in `seen`.
+		#
 		# @parameter root [Object] The root object to start traversal from.
+		# @parameter seen [Hash(Object, Integer)] The seen objects (should be compare_by_identity).
+		# @parameter via [Hash(Object, Object) | Nil] The traversal path. The key object was seen via the value object.
 		# @returns [Usage] The usage of the object and all reachable objects from it.
-		def self.of(root, seen: Set.new.compare_by_identity, ignore: IGNORE)
+		def self.of(root, seen: Set.new.compare_by_identity, ignore: IGNORE, via: nil)
 			count = 0
 			size = 0
 			
 			queue = [root]
-			while queue.any?
-				object = queue.shift
-				
-				# Skip ignored types:
-				next if ignore.any?{|type| object.is_a?(type)}
-				
-				# Skip internal objects - they don't behave correctly when added to `seen` and create unbounded recursion:
-				next if object.is_a?(ObjectSpace::InternalObjectWrapper)
-				
-				# Skip objects we have already seen:
-				next if seen.include?(object)
-				
-				# Add the object to the seen set and update the count and size:
+			while object = queue.shift
+				# Add the object to the seen set:
 				seen.add(object)
+				
+				# Update the count and size:
 				count += 1
 				size += ObjectSpace.memsize_of(object)
 				
 				# Add the object's reachable objects to the queue:
-				if reachable_objects = ObjectSpace.reachable_objects_from(object)
-					queue.concat(reachable_objects)
+				ObjectSpace.reachable_objects_from(object)&.each do |reachable_object|
+					# Skip ignored types:
+					next if ignore.any?{|type| reachable_object.is_a?(type)}
+					
+					# Skip internal objects - they don't behave correctly when added to `seen` and create unbounded recursion:
+					next if reachable_object.is_a?(ObjectSpace::InternalObjectWrapper)
+					
+					# Skip objects we have already seen:
+					next if seen.include?(reachable_object)
+					
+					if via
+						via[reachable_object] ||= object
+					end
+					
+					queue << reachable_object
 				end
 			end
 			

data/lib/memory/version.rb

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

data/lib/memory.rb

@@ -11,6 +11,8 @@ require_relative "memory/version"
 require_relative "memory/cache"
 require_relative "memory/report"
 require_relative "memory/sampler"
+require_relative "memory/usage"
+require_relative "memory/graph"
 
 # Memory profiler for Ruby applications.
 # Provides tools to track and analyze memory allocations and retention.

data/readme.md

@@ -94,6 +94,11 @@ end
 
 Please see the [project releases](https://socketry.github.io/memory/releases/index) for all releases.
 
+### v0.10.0
+
+  - Add support for `Memory::Usage.of(..., via:)` for tracking reachability of objects.
+  - Introduce `Memory::Graph` for computing paths between parent/child objects.
+
 ### v0.9.0
 
   - Explicit `ignore:` and `seen:` parameters for `Memory::Usage.of` to allow customization of ignored types and tracking of seen objects.

data/releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## v0.10.0
+
+  - Add support for `Memory::Usage.of(..., via:)` for tracking reachability of objects.
+  - Introduce `Memory::Graph` for computing paths between parent/child objects.
+
 ## v0.9.0
 
   - Explicit `ignore:` and `seen:` parameters for `Memory::Usage.of` to allow customization of ignored types and tracking of seen objects.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memory
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Sam Saffron
@@ -117,6 +117,7 @@ files:
 - lib/memory/cache.rb
 - lib/memory/deque.rb
 - lib/memory/format.rb
+- lib/memory/graph.rb
 - lib/memory/report.rb
 - lib/memory/sampler.rb
 - lib/memory/usage.rb