memory 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 610a559d7ecf64e0ec26f443e53492bcc8853f4c2a384ccb4384bf14855b9805
-  data.tar.gz: 53c34a593cf01eb64661d762b46a5a1e2d0b4ef3597f399cf6c2be76244ad2d4
+  metadata.gz: 91e6bf9d1a607a68dd5d8f368d6dfe4a4319bf5730b6283194f99fb587b96364
+  data.tar.gz: 9a4335bfa899416c7fec144236dc5e711382f49f5631a4b0dbde03d73e84a58e
 SHA512:
-  metadata.gz: 3d014fe210c6b215773e275a7b9caa1ddcf346dae6fb21e06c637d01b638ff193154b77e3e4b54a6f9fca7a92bb9d18a8d56bf75ea0cc057d2749fe6b75b5d47
-  data.tar.gz: 7918321809f910e3979384a44863e02f6c37e797918caf6e1524103e4a808be847a2bec37ddc1a1cbf35e761e45c15aef2fb4f85d521828ae252e0a5042660d5
+  metadata.gz: 0a704a533f5ac299f5b0da35814c7d93d13dc9881fda6c69c8f274a9331dedf3f9b57e1afa22b28888892092f2daf9a0c583259fbcbf26757d2f3c3805594caf
+  data.tar.gz: cc67f1e0781d93b648ed720efb1a4ce6d05c5d18c15e2b781ecbb00321fec08c674d2be2a051f1835bf9de1f2e1a90c5ee6df4be72ac46d0e4ba6f50ec48f5f5

data/lib/memory/graph.rb

@@ -3,139 +3,215 @@
 # Released under the MIT License.
 # Copyright, 2025, by Samuel Williams.
 
-require "set"
+require_relative "usage"
+require "json"
 
 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
+	module Graph
+		IGNORE = Usage::IGNORE
 		
-		# 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
+		# Represents a node in the object graph with usage information.
+		class Node
+			def initialize(object, usage = Usage.new, parent = nil, reference: nil)
+				@object = object
+				@usage = usage
+				@parent = parent
+				@children = nil
+				
+				@reference = reference || parent&.find_reference(object)
+				@total_usage = nil
+				@path = nil
+			end
+			
+			# @attribute [Object] The object this node represents.
+			attr_accessor :object
+			
+			# @attribute [Usage] The memory usage of this object (not including children).
+			attr_accessor :usage
+			
+			# @attribute [Node | Nil] The parent node (nil for root).
+			attr_accessor :parent
+			
+			# @attribute [Hash(String, Node) | Nil] Child nodes reachable from this object (hash of reference => node).
+			attr_accessor :children
+			
+			# @attribute [String | Nil] The reference to the parent object (nil for root).
+			attr_accessor :reference
+			
+			# Add a child node to this node.
+			#
+			# @parameter child [Node] The child node to add.
+			# @returns [self] Returns self for chaining.
+			def add(child)
+				@children ||= {}
+				
+				# Use the reference as the key, or a fallback if not found:
+				key = child.reference || "(#{@children.size})"
+				
+				@children[key] = child
+				
+				return self
 			end
 			
-			# Check array elements:
-			if parent.is_a?(Array)
-				parent.each_with_index do |element, index|
-					if element.equal?(child)
-						return "[#{index}]"
+			# Compute total usage including all children.
+			def total_usage
+				unless @total_usage 
+					@total_usage = Usage.new(@usage.size, @usage.count)
+					
+					@children&.each_value do |child|
+						child_total = child.total_usage
+						@total_usage.add!(child_total)
 					end
 				end
+				
+				return @total_usage
 			end
 			
-			# Check hash keys and values:
-			if parent.is_a?(Hash)
-				parent.each do |key, value|
+			# Find how this node references a child 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(child)
+				# Check instance variables:
+				@object.instance_variables.each do |ivar|
+					value = @object.instance_variable_get(ivar)
 					if value.equal?(child)
-						return "[#{key.inspect}]"
+						return ivar.to_s
 					end
-					if key.equal?(child)
-						return "(key: #{key.inspect})"
+				end
+				
+				# Check array elements:
+				if @object.is_a?(Array)
+					@object.each_with_index do |element, index|
+						if element.equal?(child)
+							return "[#{index}]"
+						end
+					end
+				end
+				
+				# Check hash keys and values:
+				if @object.is_a?(Hash)
+					@object.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 @object.is_a?(Struct)
+					@object.each_pair do |member, value|
+						if value.equal?(child)
+							return ".#{member}"
+						end
 					end
 				end
+				
+				# Could not determine the reference:
+				return nil
 			end
 			
-			# Check struct members:
-			if parent.is_a?(Struct)
-				parent.each_pair do |member, value|
-					if value.equal?(child)
-						return ".#{member}"
+			# Get the path string from root to this node (cached).
+			#
+			# @returns [String | Nil] The formatted path string, or nil if no graph available.
+			def path
+				unless @path
+					# Build object path from root to this node:
+					object_path = []
+					current = self
+					
+					while current
+						object_path.unshift(current)
+						current = current.parent
+					end
+					
+					# Format the path:
+					parts = ["#<#{object_path.first.object.class}:0x%016x>" % (object_path.first.object.object_id << 1)]
+					
+					# Append each reference in the path:
+					(1...object_path.size).each do |i|
+						parent_node = object_path[i - 1]
+						child_node = object_path[i]
+						
+						parts << (parent_node.find_reference(child_node.object) || "<??>")
 					end
+					
+					@path = parts.join
 				end
+				
+				return @path
 			end
 			
-			# Could not determine the reference:
-			return nil
+			# Convert this node to a JSON-compatible hash.
+			#
+			# @parameter options [Hash] Options for JSON serialization.
+			# @returns [Hash] A hash representation of this node.
+			def as_json(*)
+				{
+					path: path,
+						object: {
+							class: @object.class.name,
+							object_id: @object.object_id
+						},
+						usage: @usage.as_json,
+						total_usage: total_usage.as_json,
+						children: @children&.transform_values(&:as_json)
+				}
+			end
+			
+			# Convert this node to a JSON string.
+			#
+			# @parameter options [Hash] Options for JSON serialization.
+			# @returns [String] A JSON string representation of this node.
+			def to_json(...)
+				as_json.to_json(...)
+			end
 		end
 		
-		# Construct a human-readable path from an object back to a root.
+		# Build a graph of nodes from a root object, computing usage at each level.
 		#
-		# @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)
+		# @parameter root [Object] The root object to start from.
+		# @parameter depth [Integer] Maximum depth to traverse (nil for unlimited).
+		# @parameter seen [Set] Set of already seen objects (for internal use).
+		# @parameter ignore [Array] Array of types to ignore during traversal.
+		# @parameter parent [Node | Nil] The parent node (for internal use).
+		# @returns [Node] The root node with children populated.
+		def self.for(root, depth: nil, seen: Set.new.compare_by_identity, ignore: IGNORE, parent: nil)
+			if depth && depth <= 0
+				# Compute shallow usage for this object and it's children:
+				usage = Usage.of(root, seen: seen, ignore: ignore)
+				return Node.new(root, usage, parent)
 			end
 			
-			# Reverse to get path from root to object:
-			object_path.reverse!
+			# Compute shallow usage for just this object:
+			usage = Usage.new(ObjectSpace.memsize_of(root), 1)
 			
-			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]
+			# Create the node:
+			node = Node.new(root, usage, parent)
+			
+			# Mark this object as seen:
+			seen.add(root)
+			
+			# Traverse children:
+			ObjectSpace.reachable_objects_from(root)&.each do |reachable_object|
+				# Skip ignored types:
+				next if ignore.any?{|type| reachable_object.is_a?(type)}
 				
-				parts << (find_reference(parent, child) || "<??>")
+				# Skip internal objects:
+				next if reachable_object.is_a?(ObjectSpace::InternalObjectWrapper)
+				
+				# Skip already seen objects:
+				next if seen.include?(reachable_object)
+				
+				# Recursively build child node:
+				node.add(self.for(reachable_object, depth: depth ? depth - 1 : nil, seen: seen, ignore: ignore, parent: node))
 			end
 			
-			return parts.join
+			return node
 		end
 	end
 end
-

data/lib/memory/usage.rb

@@ -39,6 +39,15 @@ module Memory
 			return self
 		end
 		
+		# Add another usage to this usage.
+		# @parameter other [Usage] The usage to add.
+		def add!(other)
+			self.size += other.size
+			self.count += other.count
+			
+			return self
+		end
+		
 		IGNORE = [
 			# Skip modules and symbols, they are usually "global":
 			Module,
@@ -62,9 +71,8 @@ module Memory
 		#
 		# @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, via: nil)
+		def self.of(root, seen: Set.new.compare_by_identity, ignore: IGNORE)
 			count = 0
 			size = 0
 			
@@ -88,10 +96,6 @@ module Memory
 					# 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.10.0"
+	VERSION = "0.11.0"
 end

data/readme.md

@@ -94,6 +94,10 @@ end
 
 Please see the [project releases](https://socketry.github.io/memory/releases/index) for all releases.
 
+### v0.11.0
+
+  - Remove support for `Memory::Usage.of(..., via:)` and instead use `Memory::Graph.for` which collects more detailed usage until the specified depth, at which point it delgates to `Memory::Usage.of`. This should be more practical.
+
 ### v0.10.0
 
   - Add support for `Memory::Usage.of(..., via:)` for tracking reachability of objects.
@@ -132,10 +136,6 @@ Please see the [project releases](https://socketry.github.io/memory/releases/ind
 
   - Add `Memory::Sampler#as_json` and `#to_json`.
 
-### v0.6.0
-
-  - Add agent context.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.11.0
+
+  - Remove support for `Memory::Usage.of(..., via:)` and instead use `Memory::Graph.for` which collects more detailed usage until the specified depth, at which point it delgates to `Memory::Usage.of`. This should be more practical.
+
 ## v0.10.0
 
   - Add support for `Memory::Usage.of(..., via:)` for tracking reachability of objects.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memory
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Sam Saffron