memory 0.8.4 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbe94b9b53feb63ebeef3069e3632f08084467a2670714f9680c881a88a3f133
-  data.tar.gz: 95c23b5b6cd0be124e9370b7631118bf24e5fbcc0b19091588d01ff723769d06
+  metadata.gz: 610a559d7ecf64e0ec26f443e53492bcc8853f4c2a384ccb4384bf14855b9805
+  data.tar.gz: 53c34a593cf01eb64661d762b46a5a1e2d0b4ef3597f399cf6c2be76244ad2d4
 SHA512:
-  metadata.gz: b94371ccdf66d56362320b83370c9b59d7db1d4b75d62c8506fa19392cf9da62b14eaecf8c981f518edf18c10bb65627c55687146c7fe9af0c4faa3a92f86982
-  data.tar.gz: 764fc3157811e87be1a6d220425ee5c1c3135c9e47a3ce99066968d82948f8cbdf01dad47538cf22ac25a062c2d5c486bff024fa5ee862686779dade668dc046
+  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

@@ -39,37 +39,60 @@ module Memory
 			return self
 		end
 		
+		IGNORE = [
+			# Skip modules and symbols, they are usually "global":
+			Module,
+			# Note that `reachable_objects_from` does not include symbols, numbers, or other value types, AFAICT.
+			
+			Proc,
+			Method,
+			UnboundMethod,
+			Binding,
+			TracePoint,
+			
+			# We don't want to traverse into shared state:
+			Ractor,
+			Thread,
+			Fiber
+		]
+		
 		# 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
-			
+		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 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 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.8.4"
+	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,15 @@ 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.
+
 ### v0.8.4
 
   - Fix bugs when printing reports due to interface mismatch with `Memory::Usage`.

data/releases.md

@@ -1,5 +1,14 @@
 # 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.
+
 ## v0.8.4
 
   - Fix bugs when printing reports due to interface mismatch with `Memory::Usage`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memory
 version: !ruby/object:Gem::Version
-  version: 0.8.4
+  version: 0.10.0
 platform: ruby
 authors:
 - Sam Saffron
@@ -29,7 +29,6 @@ authors:
 - Olle Jonsson
 - Vasily Kolesnikov
 - William Tabi
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -61,7 +60,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-10-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bake
@@ -105,8 +104,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -120,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
@@ -133,7 +131,6 @@ licenses:
 metadata:
   documentation_uri: https://socketry.github.io/memory/
   source_code_uri: https://github.com/socketry/memory.git
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -148,8 +145,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Memory profiling routines for Ruby 2.3+
 test_files: []