memory 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 535ecdd0c6181d94b31384e4f71b4b4ce52d499d43daa647120fb22cf3dc244b
-  data.tar.gz: bfc66be86d65f7065ebc6a4193420ccbe50a98ad5e581ba6cf613484d1846012
+  metadata.gz: 91e6bf9d1a607a68dd5d8f368d6dfe4a4319bf5730b6283194f99fb587b96364
+  data.tar.gz: 9a4335bfa899416c7fec144236dc5e711382f49f5631a4b0dbde03d73e84a58e
 SHA512:
-  metadata.gz: e2df82be2210853cdc3ede7d47d450d1a38bc14291ee4fdaa3bece83809ce78ffb73ae714d52da9843dbd43d2659e6a97b17005ecbf3abe1f81fe8a687b0cbc5
-  data.tar.gz: de6c8972b60a489e7f62834fe926674ed55103fae47a401ef81674b43a8a79b271a8b21051948c56b094a0372abb5493c78739265686b4c4591272ffd70b8f4b
+  metadata.gz: 0a704a533f5ac299f5b0da35814c7d93d13dc9881fda6c69c8f274a9331dedf3f9b57e1afa22b28888892092f2daf9a0c583259fbcbf26757d2f3c3805594caf
+  data.tar.gz: cc67f1e0781d93b648ed720efb1a4ce6d05c5d18c15e2b781ecbb00321fec08c674d2be2a051f1835bf9de1f2e1a90c5ee6df4be72ac46d0e4ba6f50ec48f5f5

data/lib/memory/graph.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "usage"
+require "json"
+
+module Memory
+	# Tracks object traversal paths for memory analysis.
+	module Graph
+		IGNORE = Usage::IGNORE
+		
+		# 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
+			
+			# 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
+			
+			# 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 ivar.to_s
+					end
+				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
+			
+			# 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
+			
+			# 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
+		
+		# Build a graph of nodes from a root object, computing usage at each level.
+		#
+		# @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
+			
+			# Compute shallow usage for just this object:
+			usage = Usage.new(ObjectSpace.memsize_of(root), 1)
+			
+			# 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)}
+				
+				# 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 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,
@@ -57,33 +66,37 @@ 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).
 		# @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)
 			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)
+					
+					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.11.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,15 @@ 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.
+  - 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.
@@ -127,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,14 @@
 # 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.
+  - 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.11.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