memory-profiler 1.3.0 → 1.4.0

data/ext/memory/profiler/events.h

@@ -23,7 +23,8 @@ struct Memory_Profiler_Event {
 	// The class of the object:
 	VALUE klass;
 
-	// The object itself (for NEWOBJ and FREEOBJ):
+	// The object_id (Integer VALUE) - NOT the raw object.
+	// We store object_id to avoid referencing objects that should be freed.
 	VALUE object;
 };
 
@@ -32,12 +33,13 @@ struct Memory_Profiler_Events;
 struct Memory_Profiler_Events* Memory_Profiler_Events_instance(void);
 
 // Enqueue an event to the global queue.
+// object parameter should be the object_id (Integer), not the raw object.
 // Returns non-zero on success, zero on failure.
 int Memory_Profiler_Events_enqueue(
 	enum Memory_Profiler_Event_Type type,
 	VALUE capture,
 	VALUE klass,
-	VALUE object
+	VALUE object_id
 );
 
 // Process all queued events immediately (flush the queue)

data/lib/memory/profiler/capture.rb

@@ -3,4 +3,4 @@
 # Released under the MIT License.
 # Copyright, 2025, by Samuel Williams.
 
-require "Memory_Profiler"
+require_relative "native"

data/lib/memory/profiler/graph.rb

@@ -0,0 +1,369 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "objspace"
+
+module Memory
+	module Profiler
+		class Graph
+			def initialize
+				@objects = Set.new.compare_by_identity
+				@parents = Hash.new{|hash, key| hash[key] = Set.new.compare_by_identity}.compare_by_identity
+				@internals = Set.new
+				@root = nil # Track the root of traversal for idom
+			end
+			
+			attr :parents
+			
+			def include?(object)
+				@parents.include?(object)
+			end
+			
+			def inspect
+				"#<#{self.class.name} @objects=#{@objects.size} @parents=#{@parents.size} @names=#{@names.size}>"
+			end
+			
+			def add(object)
+				@objects.add(object)
+			end
+			
+			def update!(from = Object)
+				# Store the root for idom algorithm
+				@root = from
+				@parents.clear
+				@internals.clear
+
+				# If the user has provided a specific object, try to avoid traversing the root Object.
+				if from != Object
+					@parents[Object] = nil
+				end
+				
+				# Don't traverse the graph itself:
+				@parents[self] = nil
+				
+				traverse!(from)
+			end
+			
+			def name_for(object, limit = 8)
+				if object.is_a?(Module)
+					object.name.to_s
+				elsif object.is_a?(Object)
+					if limit > 0
+						parents = @parents[object]
+						if parent = parents&.first
+							return name_for(parent, limit - 1) + compute_edge_label(parent, object)
+						end
+					end
+					
+					return object.class.name.to_s
+				else
+					object.inspect
+				end
+			end
+			
+			# Return roots using immediate dominator algorithm
+			def roots
+				return [] if @objects.empty?
+				
+				# Compute immediate dominators
+				idom = compute_idom
+				
+				# Count how many tracked objects each node dominates
+				dominated_counts = Hash.new(0).compare_by_identity
+				retained_by_counts = Hash.new(0).compare_by_identity
+				
+				@objects.each do |object|
+					# Credit the immediate dominator
+					if dominator = idom[object]
+						dominated_counts[dominator] += 1
+					end
+					
+					# Credit all immediate parents for retained_by
+					if parent_set = @parents[object]
+						parent_set.each do |parent|
+							retained_by_counts[parent] += 1
+						end
+					end
+				end
+				
+				# Build results
+				total = @objects.size
+				results = []
+				
+				dominated_counts.each do |object, count|
+					result = {
+						name: name_for(object),
+							count: count,
+							percentage: (count * 100.0) / total
+					}
+					
+					if retained_count = retained_by_counts[object]
+						result[:retained_by] = retained_count
+					end
+					
+					results << result
+				end
+				
+				# Add entries that appear ONLY in retained_by (intermediate nodes)
+				retained_by_counts.each do |object, count|
+					next if dominated_counts[object]  # Already included
+					
+					results << {
+						name: name_for(object),
+						count: 0,
+						percentage: 0.0,
+						retained_by: count
+					}
+				end
+				
+				# Sort by count descending
+				results.sort_by!{|r| -r[:count]}
+				
+				results
+			end
+			
+		private
+
+			IS_A = Kernel.method(:is_a?).unbind
+			RESPOND_TO = Kernel.method(:respond_to?).unbind
+			EQUAL = Kernel.method(:equal?).unbind
+			
+			def traverse!(object, parent = nil)
+				queue = Array.new
+				queue << [object, parent]
+				
+				while queue.any?
+					object, parent = queue.shift
+					
+					# We shouldn't use internal objects as parents.
+					unless IS_A.bind_call(object, ObjectSpace::InternalObjectWrapper)
+						parent = object
+					end
+					
+					ObjectSpace.reachable_objects_from(object).each do |child|
+						if IS_A.bind_call(child, ObjectSpace::InternalObjectWrapper)
+							# There is no value in scanning internal objects.
+							next if child.type == :T_IMEMO
+
+							# We need to handle internal objects differently, because they don't follow the same equality/identity rules. Since we can reach the same internal object from multiple parents, we need to use an appropriate key to track it. Otherwise, the objects will not be counted on subsequent parent traversals.
+							key = [parent.object_id, child.internal_object_id]
+							if @internals.add?(key)
+								queue << [child, parent]
+							end
+						elsif parents = @parents[child] # Skip traversal if we are explicitly set to nil.
+							# If we haven't seen the object yet, add it to the queue:
+							if parents.add?(parent)
+								queue << [child, parent]
+							end
+						end
+					end
+				end
+			end
+			
+			# Limit the cost of computing the edge label.
+			SEARCH_LIMIT = 1000
+			
+			# Lazily compute the edge label (how parent references child)
+			# This is called on-demand for objects that appear in roots
+			def compute_edge_label(parent, object)
+				case parent
+				when Hash
+					if parent.size < SEARCH_LIMIT
+						# Use Ruby's built-in key method to find the key
+						if key = parent.key(object)
+							return "[#{key.inspect}]"
+						end
+					end
+					return "[?/#{parent.size}]"
+				when Array
+					if parent.size < SEARCH_LIMIT
+						# Use Ruby's built-in index method to find the position
+						if index = parent.index(object)
+							return "[#{index}]"
+						end
+					end
+					return "[?/#{parent.size}]"
+				else
+					return extract_name(parent, object)
+				end
+			rescue => error
+				# If inspection fails, fall back to class name
+				return "(#{error.class.name}: #{error.message})"
+			end
+			
+			# Compute immediate dominators for all nodes
+			# Returns hash mapping node => immediate dominator
+			def compute_idom
+				idom = Hash.new.compare_by_identity
+				
+				# Root dominates itself
+				idom[@root] = @root if @root
+				
+				# Find all roots (nodes with no parents)
+				roots = Set.new.compare_by_identity
+				roots.add(@root) if @root
+				
+				# Convert to array to avoid "can't add key during iteration" errors
+				@parents.each do |node, parents|
+					if parents.nil? || parents.empty?
+						roots.add(node)
+						idom[node] = node
+					end
+				end
+				
+				# Iterative dataflow analysis
+				changed = true
+				iterations = 0
+				
+				while changed && iterations < 1000
+					changed = false
+					iterations += 1
+					
+					# Convert to array to avoid "can't add key during iteration" errors
+					@parents.each do |node, parents|
+						# Skip roots:
+						next if roots.include?(node)
+						next if parents.nil? || parents.empty?
+						
+						# Find first processed predecessor
+						new_idom = parents.find{|parent| idom[parent]}
+						next unless new_idom
+						
+						# Intersect with other processed predecessors
+						parents.each do |parent|
+							next if parent.equal?(new_idom)
+							next unless idom[parent]
+							
+							new_idom = intersect(new_idom, parent, idom)
+						end
+						
+						# Update if changed
+						if !idom[node].equal?(new_idom)
+							idom[node] = new_idom
+							changed = true
+						end
+					end
+				end
+				
+				idom
+			end
+			
+			# Find lowest common ancestor in dominator tree
+			def intersect(node1, node2, idom)
+				finger1 = node1
+				finger2 = node2
+				seen = Set.new.compare_by_identity
+				iterations = 0
+				
+				until finger1.equal?(finger2)
+					return finger1 if iterations > SEARCH_LIMIT
+					iterations += 1
+					
+					# Prevent infinite loops
+					return finger1 if seen.include?(finger1)
+					seen.add(finger1)
+					
+					# Walk up both paths until they meet
+					depth1 = depth(finger1)
+					depth2 = depth(finger2)
+					
+					if depth1 > depth2
+						break unless idom[finger1]
+						finger1 = idom[finger1]
+					elsif depth2 > depth1
+						break unless idom[finger2]
+						finger2 = idom[finger2]
+					else
+						# Same depth, walk both up
+						break unless idom[finger1] && idom[finger2]
+						finger1 = idom[finger1]
+						finger2 = idom[finger2]
+					end
+				end
+				
+				finger1
+			end
+			
+			# Compute depth of node in parent tree
+			def depth(node)
+				depth = 0
+				current = node
+				seen = Set.new.compare_by_identity
+				
+				while current
+					return depth if seen.include?(current)
+					seen.add(current)
+					
+					break unless @parents.key?(current)
+					parents = @parents[current]
+					break if parents.empty?
+					
+					current = parents.first # TODO: Should we use the first parent?
+					depth += 1
+				end
+				
+				depth
+			end
+			
+			def extract_name(parent, object)
+				if RESPOND_TO.bind_call(parent, :constants)
+					parent.constants.each do |constant|
+						if !parent.autoload?(constant) && parent.const_defined?(constant)
+							if EQUAL.bind_call(parent.const_get(constant), object)
+								return "::#{constant}"
+							end
+						end
+					end
+				end
+				
+				if RESPOND_TO.bind_call(parent, :instance_variables)
+					parent.instance_variables.each do |variable|
+						if EQUAL.bind_call(parent.instance_variable_get(variable), object)
+							return ".#{variable}"
+						end
+					end
+				end
+				
+				if IS_A.bind_call(parent, Struct)
+					parent.members.each do |member|
+						if EQUAL.bind_call(parent[member], object)
+							return ".#{member}"
+						end
+					end
+				end
+				
+				if IS_A.bind_call(parent, Fiber)
+					return "(fiber)"
+				end
+				
+				if IS_A.bind_call(parent, Thread)
+					parent.thread_variables.each do |variable|
+						if EQUAL.bind_call(parent.thread_variable_get(variable), object)
+							return "(TLS #{variable})"
+						end
+					end
+					
+					parent.keys.each do |key|
+						if EQUAL.bind_call(parent[key], object)
+							return "[#{key}]"
+						end
+					end
+					
+					return "(thread)"
+				end
+				
+				if IS_A.bind_call(parent, Ractor)
+					return "(ractor)"
+				end
+				
+				return "(#{parent.inspect}::???)"
+			rescue => error
+				# If inspection fails, fall back to class name
+				return "(#{error.class.name}: #{error.message})"
+			end
+		end
+	end
+end
+

data/lib/memory/profiler/native.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+# Load objspace first so InternalObjectWrapper is available
+require "objspace"
+
+require "Memory_Profiler"

data/lib/memory/profiler/sampler.rb

@@ -9,6 +9,7 @@ require "objspace"
 require_relative "capture"
 require_relative "allocations"
 require_relative "call_tree"
+require_relative "graph"
 
 module Memory
 	module Profiler
@@ -141,6 +142,28 @@ module Memory
 			def stop
 				@capture.stop
 			end
+
+			# Clear tracking data for a class.
+			def clear(klass)
+				tree = @call_trees[klass]
+				tree&.clear!
+			end
+			
+			# Clear all tracking data.
+			def clear_all!
+				@call_trees.each_value(&:clear!)
+				@capture.clear
+			end
+			
+			# Stop all tracking and clean up.
+			def stop!
+				@capture.stop
+				@call_trees.each_key do |klass|
+					@capture.untrack(klass)
+				end
+				@capture.clear
+				@call_trees.clear
+			end
 			
 			# Run periodic sampling in a loop.
 			#
@@ -210,9 +233,9 @@ module Memory
 				tree = @call_trees[klass] = CallTree.new
 				
 				# Register callback on allocations object:
-				# - On :newobj - returns state (leaf node) which C extension stores
-				# - On :freeobj - receives state back from C extension
-				allocations.track do |klass, event, state|
+				# - On :newobj - returns data (leaf node) which C extension stores
+				# - On :freeobj - receives data back from C extension
+				allocations.track do |klass, event, data|
 					case event
 					when :newobj
 						# Capture call stack and record in tree
@@ -224,8 +247,8 @@ module Memory
 						end
 						# Return nil or the node - C will store whatever we return.
 					when :freeobj
-						# Decrement using the state (leaf node) passed back from then native extension:
-						state&.decrement_path!
+						# Decrement using the data (leaf node) passed back from then native extension:
+						data&.decrement_path!
 					end
 				rescue Exception => error
 					warn "Error in allocation tracking: #{error.message}\n#{error.backtrace.join("\n")}"
@@ -256,45 +279,49 @@ module Memory
 			# Get allocation statistics for a tracked class.
 			#
 			# @parameter klass [Class] The class to get statistics for.
-			# @returns [Hash] Statistics including total, retained, paths, and hotspots.
-			def analyze(klass)
-				call_tree = @call_trees[klass]
+			# @parameter allocation_roots [Boolean] Include call tree showing where allocations occurred (default: true if available).
+			# @parameter retained_roots [Boolean] Compute object graph showing what's retaining allocations (default: true, can be slow for large graphs).
+			# @parameter roots_from [Object] Starting point for retained roots analysis (default: Object).
+			# @returns [Hash] Statistics including allocations, allocation_roots (call tree), and retained_roots (object graph).
+			def analyze(klass, allocation_roots: true, retained_roots: false, retained_objects: true)
+				call_tree_data = @call_trees[klass] if allocation_roots
 				allocations = @capture[klass]
 				
-				return nil unless call_tree or allocations
+				return nil unless call_tree_data or allocations
 				
-				{
+				result = {
 					allocations: allocations&.as_json,
-					call_tree: call_tree&.as_json
 				}
-			end
-			
-			# @deprecated Use {analyze} instead.
-			alias statistics analyze
-			
-			# Clear tracking data for a class.
-			def clear(klass)
-				tree = @call_trees[klass]
-				tree&.clear!
-			end
-			
-			# Clear all tracking data.
-			def clear_all!
-				@call_trees.each_value(&:clear!)
-				@capture.clear
-			end
-			
-			# Stop all tracking and clean up.
-			def stop!
-				@capture.stop
-				@call_trees.each_key do |klass|
-					@capture.untrack(klass)
+				
+				if allocation_roots && call_tree_data
+					result[:allocation_roots] = call_tree_data.as_json
 				end
-				@capture.clear
-				@call_trees.clear
+				
+				if retained_roots
+					result[:retained_roots] = compute_roots(klass)
+				end
+				
+				result
 			end
 			
 		private
+
+			# Compute retaining roots for a class's allocations
+			def compute_roots(klass)
+				graph = Graph.new
+				
+				# Add all tracked objects to the graph
+				# NOTE: States table is now at Capture level, so we use capture.each_object
+				@capture.each_object(klass) do |object, state|
+					graph.add(object)
+				end
+				
+				# Build parent relationships
+				graph.update!
+				
+				# Return roots analysis
+				graph.roots
+			end
 			
 			# Default filter to include all locations.
 			def default_filter

data/lib/memory/profiler/version.rb

@@ -7,7 +7,7 @@
 module Memory
 	# @namespace
 	module Profiler
-		VERSION = "1.3.0"
+		VERSION = "1.4.0"
 	end
 end
 

data/lib/memory/profiler.rb

@@ -8,3 +8,4 @@ require_relative "profiler/call_tree"
 require_relative "profiler/capture"
 require_relative "profiler/allocations"
 require_relative "profiler/sampler"
+require_relative "profiler/graph"

data/readme.md

@@ -22,6 +22,11 @@ Please see the [project documentation](https://socketry.github.io/memory-profile
 
 Please see the [project releases](https://socketry.github.io/memory-profiler/releases/index) for all releases.
 
+### v1.4.0
+
+  - Implement [Cooper-Harvey-Kennedy](https://www.cs.tufts.edu/~nr/cs257/archive/keith-cooper/dom14.pdf) algorithm for finding root objects in memory leaks.
+  - Rework capture to track objects by `object_id` exclusively.
+
 ### v1.3.0
 
   - **Breaking**: Renamed `Capture#count_for` to `Capture#retained_count_of` for better clarity and consistency.
@@ -75,10 +80,6 @@ Please see the [project releases](https://socketry.github.io/memory-profiler/rel
 
   - More write barriers...
 
-### v1.1.8
-
-  - Use single global queue for event handling to avoid incorrect ordering.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## v1.4.0
+
+  - Implement [Cooper-Harvey-Kennedy](https://www.cs.tufts.edu/~nr/cs257/archive/keith-cooper/dom14.pdf) algorithm for finding root objects in memory leaks.
+  - Rework capture to track objects by `object_id` exclusively.
+
 ## v1.3.0
 
   - **Breaking**: Renamed `Capture#count_for` to `Capture#retained_count_of` for better clarity and consistency.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memory-profiler
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -59,6 +59,8 @@ files:
 - lib/memory/profiler/allocations.rb
 - lib/memory/profiler/call_tree.rb
 - lib/memory/profiler/capture.rb
+- lib/memory/profiler/graph.rb
+- lib/memory/profiler/native.rb
 - lib/memory/profiler/sampler.rb
 - lib/memory/profiler/version.rb
 - license.md