Introduce Memory::Graph.

Author: samuel-williams-shopify

lib/memory.rb

@@ -11,6 +11,8 @@
 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.

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
+

lib/memory/usage.rb

@@ -57,33 +57,42 @@ def << allocation
 		]
 
 		# 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
 

releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## Unreleased
+
+  - 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.