memory-profiler 1.1.15 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cce184966c5eb2b104059f419fb7f220b2bea168b5359adacc90923079332241
-  data.tar.gz: 436690f9e75f5ba72546604fd58d71efccb56d4dc8b8880feaa3b4ecab03c918
+  metadata.gz: f059f309b7c1fd6fcffd119a0f6d40e8d4480783e2955ad3fc054fa280015f9d
+  data.tar.gz: e3c1ddd9afd7240b3bf727f6b6219b2bcb2e164c8e9c1c245ac4163684b180b8
 SHA512:
-  metadata.gz: 54d4d1e2f8d19da788e53ffa0c5e69dcaf5db708d5d1de0336bccc79c6311330a56b0c8cb605b7bb7dbc116b91b91a752cacf317d4403e5188517ddcdded12a2
-  data.tar.gz: 4994f81f0b6dd2b0c46bc3aa3e415dbc16ffb633d9fefdeafd67d10df522aaccc5003dd632a664b8eb69e476053bac5f51d0979c69c4daa97965356b1bb2ca9c
+  metadata.gz: 2bd209fd9a3c9f3116bf0c76b405c1fed1580f5412292646749539f73eb5e2b7334e2267a5bbd43fbc4c13fa7c8385422e32f369779e62f022966e56108a46c3
+  data.tar.gz: 6e38c7368db453b2476a0084bbcdca8c60df5d0c51d2395df5e23c18a2b4f49f3bbbd64f5e562af2a02e91a0cd73b6cc129000eb80f75e485afbfe3b9d769ff2

data/ext/memory/profiler/allocations.c

@@ -143,13 +143,24 @@ void Memory_Profiler_Allocations_clear(VALUE allocations) {
 	}
 }
 
+// Allocate a new Allocations object (for testing)
+static VALUE Memory_Profiler_Allocations_allocate(VALUE klass) {
+	struct Memory_Profiler_Capture_Allocations *record = ALLOC(struct Memory_Profiler_Capture_Allocations);
+	record->callback = Qnil;
+	record->new_count = 0;
+	record->free_count = 0;
+	record->states = st_init_numtable();
+	
+	return Memory_Profiler_Allocations_wrap(record);
+}
+
 void Init_Memory_Profiler_Allocations(VALUE Memory_Profiler)
 {
 	// Allocations class - wraps allocation data for a specific class
 	Memory_Profiler_Allocations = rb_define_class_under(Memory_Profiler, "Allocations", rb_cObject);
 	
-	// Allocations objects are only created internally via wrap, never from Ruby:
-	rb_undef_alloc_func(Memory_Profiler_Allocations);
+	// Allow allocation for testing
+	rb_define_alloc_func(Memory_Profiler_Allocations, Memory_Profiler_Allocations_allocate);
 	
 	rb_define_method(Memory_Profiler_Allocations, "new_count", Memory_Profiler_Allocations_new_count, 0);
 	rb_define_method(Memory_Profiler_Allocations, "free_count", Memory_Profiler_Allocations_free_count, 0);

data/ext/memory/profiler/capture.c

@@ -469,7 +469,7 @@ static VALUE Memory_Profiler_Capture_tracking_p(VALUE self, VALUE klass) {
 }
 
 // Get count of live objects for a specific class (O(1) lookup!)
-static VALUE Memory_Profiler_Capture_count_for(VALUE self, VALUE klass) {
+static VALUE Memory_Profiler_Capture_retained_count_of(VALUE self, VALUE klass) {
 	struct Memory_Profiler_Capture *capture;
 	TypedData_Get_Struct(self, struct Memory_Profiler_Capture, &Memory_Profiler_Capture_type, capture);
 	
@@ -641,7 +641,7 @@ void Init_Memory_Profiler_Capture(VALUE Memory_Profiler)
 	rb_define_method(Memory_Profiler_Capture, "track", Memory_Profiler_Capture_track, -1);  // -1 to accept block
 	rb_define_method(Memory_Profiler_Capture, "untrack", Memory_Profiler_Capture_untrack, 1);
 	rb_define_method(Memory_Profiler_Capture, "tracking?", Memory_Profiler_Capture_tracking_p, 1);
-	rb_define_method(Memory_Profiler_Capture, "count_for", Memory_Profiler_Capture_count_for, 1);
+	rb_define_method(Memory_Profiler_Capture, "retained_count_of", Memory_Profiler_Capture_retained_count_of, 1);
 	rb_define_method(Memory_Profiler_Capture, "each", Memory_Profiler_Capture_each, 0);
 	rb_define_method(Memory_Profiler_Capture, "[]", Memory_Profiler_Capture_aref, 1);
 	rb_define_method(Memory_Profiler_Capture, "clear", Memory_Profiler_Capture_clear, 0);

data/lib/memory/profiler/allocations.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "capture"
+
+module Memory
+	module Profiler
+		# Ruby extensions to the C-defined Allocations class.
+		# The base Allocations class is defined in the C extension.
+		class Allocations
+			# Convert allocation statistics to JSON-compatible hash.
+			#
+			# @returns [Hash] Allocation statistics as a hash.
+			def as_json(...)
+				{
+					new_count: self.new_count,
+					free_count: self.free_count,
+					retained_count: self.retained_count,
+				}
+			end
+			
+			# Convert allocation statistics to JSON string.
+			#
+			# @returns [String] Allocation statistics as JSON.
+			def to_json(...)
+				as_json.to_json(...)
+			end
+		end
+	end
+end
+

data/lib/memory/profiler/call_tree.rb

@@ -187,7 +187,7 @@ module Memory
 			# @parameter limit [Integer] Maximum number of paths to return.
 			# @parameter by [Symbol] Sort by :total or :retained count.
 			# @returns [Array(Array)] Array of [locations, total_count, retained_count].
-			def top_paths(limit = 10, by: :retained)
+			def top_paths(limit: 10, by: :retained)
 				paths = []
 				
 				@root.each_path do |path, total_count, retained_count|
@@ -206,7 +206,7 @@ module Memory
 			# @parameter limit [Integer] Maximum number of hotspots to return.
 			# @parameter by [Symbol] Sort by :total or :retained count.
 			# @returns [Hash] Map of location => [total_count, retained_count].
-			def hotspots(limit = 20, by: :retained)
+			def hotspots(limit: 20, by: :retained)
 				frames = Hash.new{|h, k| h[k] = [0, 0]}
 				
 				collect_frames(@root, frames)
@@ -245,6 +245,29 @@ module Memory
 				@root.prune!(limit)
 			end
 			
+			# Convert call tree data to JSON-compatible hash.
+			#
+			# @returns [Hash] Call tree data as a hash.
+			def as_json(top_paths: {limit: 10}, hotspots: {limit: 20})
+				{
+					total_allocations: total_allocations,
+						retained_allocations: retained_allocations,
+						top_paths: top_paths(**top_paths).map{|path, total, retained| 
+							{path: path, total_count: total, retained_count: retained}
+						},
+						hotspots: hotspots(**hotspots).transform_values{|total, retained|
+							{total_count: total, retained_count: retained}
+						}
+				}
+			end
+			
+			# Convert call tree data to JSON string.
+			#
+			# @returns [String] Call tree data as JSON.
+			def to_json(...)
+				as_json.to_json(...)
+			end
+			
 		private
 			
 			def collect_frames(node, frames)

data/lib/memory/profiler/sampler.rb

@@ -7,6 +7,7 @@ require "console"
 require "objspace"
 
 require_relative "capture"
+require_relative "allocations"
 require_relative "call_tree"
 
 module Memory
@@ -93,12 +94,15 @@ module Memory
 			# @parameter increases_threshold [Integer] Number of increases before enabling detailed tracking.
 			# @parameter prune_limit [Integer] Keep only top N children per node during pruning (default: 5).
 			# @parameter prune_threshold [Integer] Number of insertions before auto-pruning (nil = no auto-pruning).
-			def initialize(depth: 4, filter: nil, increases_threshold: 10, prune_limit: 5, prune_threshold: nil)
+			# @parameter gc [Hash | Nil] Run GC with these options before each sample (nil = don't run GC).
+			def initialize(depth: 4, filter: nil, increases_threshold: 10, prune_limit: 5, prune_threshold: nil, gc: nil)
 				@depth = depth
 				@filter = filter || default_filter
 				@increases_threshold = increases_threshold
 				@prune_limit = prune_limit
 				@prune_threshold = prune_threshold
+				@gc = gc
+				
 				@capture = Capture.new
 				@call_trees = {}
 				@samples = {}
@@ -150,6 +154,9 @@ module Memory
 				while true
 					start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 					
+					# Optional garbage collection before sampling can help reduce noise:
+					GC.start(**@gc) if @gc
+					
 					sample!(&block)
 					
 					# Log capture statistics to detect issues like missing FREEOBJ events:
@@ -169,15 +176,22 @@ module Memory
 				@capture.each do |klass, allocations|
 					count = allocations.retained_count
 					sample = @samples[klass] ||= Sample.new(klass, count)
+					increased = false
 					
 					if sample.sample!(count)
+						increased = true
+						
 						# Check if we should enable detailed tracking
-						if sample.increases >= @increases_threshold && !@call_trees.key?(klass)
-							track(klass, allocations)
+						if sample.increases >= @increases_threshold
+							# Start tracking with call path analysis if not already doing so:
+							unless tracking?(klass)
+								track(klass, allocations)
+							end
 						end
-						
-						# Notify about growth if block given
-						yield sample if block_given?
+					end
+					
+					if block_given?
+						yield sample, increased
 					end
 				end
 				
@@ -188,14 +202,12 @@ module Memory
 			# Start tracking with call path analysis.
 			#
 			# @parameter klass [Class] The class to track with detailed analysis.
-			def track(klass, allocations = nil)
+			def track(klass, allocations = nil, filter: @filter, depth: @depth)
 				# Track the class and get the allocations object
 				allocations ||= @capture.track(klass)
 				
 				# Set up call tree for this class
 				tree = @call_trees[klass] = CallTree.new
-				depth = @depth
-				filter = @filter
 				
 				# Register callback on allocations object:
 				# - On :newobj - returns state (leaf node) which C extension stores
@@ -233,7 +245,7 @@ module Memory
 			
 			# Get live object count for a class.
 			def count(klass)
-				@capture.count_for(klass)
+				@capture.retained_count_of(klass)
 			end
 			
 			# Get the call tree for a specific class.
@@ -245,29 +257,20 @@ module Memory
 			#
 			# @parameter klass [Class] The class to get statistics for.
 			# @returns [Hash] Statistics including total, retained, paths, and hotspots.
-			def statistics(klass)
-				tree = @call_trees[klass]
-				return nil unless tree
+			def analyze(klass)
+				call_tree = @call_trees[klass]
+				allocations = @capture[klass]
+				
+				return nil unless call_tree or allocations
 				
 				{
-					live_count: @capture.count_for(klass),
-					total_allocations: tree.total_allocations,
-					retained_allocations: tree.retained_allocations,
-					top_paths: tree.top_paths(10).map{|path, total, retained| 
-						{path: path, total_count: total, retained_count: retained}
-					},
-					hotspots: tree.hotspots(20).transform_values{|total, retained|
-						{total_count: total, retained_count: retained}
-					}
+					allocations: allocations&.as_json,
+					call_tree: call_tree&.as_json
 				}
 			end
 			
-			# Get statistics for all tracked classes.
-			def all_statistics
-				@call_trees.keys.each_with_object({}) do |klass, result|
-					result[klass] = statistics(klass) if tracking?(klass)
-				end
-			end
+			# @deprecated Use {analyze} instead.
+			alias statistics analyze
 			
 			# Clear tracking data for a class.
 			def clear(klass)
@@ -293,8 +296,9 @@ module Memory
 			
 		private
 			
+			# Default filter to include all locations.
 			def default_filter
-				->(location) {!location.path.match?(%r{/(gems|ruby)/|\A\(eval\)})}
+				->(location) {true}
 			end
 			
 			def prune_call_trees!

data/lib/memory/profiler/version.rb

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

data/lib/memory/profiler.rb

@@ -6,4 +6,5 @@
 require_relative "profiler/version"
 require_relative "profiler/call_tree"
 require_relative "profiler/capture"
+require_relative "profiler/allocations"
 require_relative "profiler/sampler"

data/readme.md

@@ -22,6 +22,25 @@ 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.3.0
+
+  - **Breaking**: Renamed `Capture#count_for` to `Capture#retained_count_of` for better clarity and consistency.
+  - **Breaking**: Changed `CallTree#top_paths(limit)` to `CallTree#top_paths(limit:)` - now uses keyword argument.
+  - **Breaking**: Changed `CallTree#hotspots(limit)` to `CallTree#hotspots(limit:)` - now uses keyword argument.
+  - Simplified `Sampler#analyze` return structure to `{allocations: {...}, call_tree: {...}}` format.
+  - Added `Allocations#as_json` and `Allocations#to_json` methods for JSON serialization.
+  - Added `CallTree#as_json` and `CallTree#to_json` methods for JSON serialization with configurable options.
+  - `Memory::Profiler::Allocations.new` can now be instantiated directly (primarily for testing).
+  - `Sampler#statistics` is now a deprecated alias for `Sampler#analyze`.
+  - **Breaking**: Removed `Sampler#all_statistics` method.
+
+### v1.2.0
+
+  - Enable custom `depth:` and `filter:` options to `Sampler#track`.
+  - Change default filter to no-op.
+  - Add option to run GC with custom options before each sample to reduce noise.
+  - Always report sampler statistics after each sample.
+
 ### v1.1.15
 
   - Ignore `freeobj` for classes that are not being tracked.
@@ -60,16 +79,6 @@ Please see the [project releases](https://socketry.github.io/memory-profiler/rel
 
   - Use single global queue for event handling to avoid incorrect ordering.
 
-### v1.1.7
-
-  - Expose `Capture#statistics` for debugging internal memory tracking state.
-
-### v1.1.6
-
-  - Write barriers all the things.
-  - Better state handling and object increment/decrement counting.
-  - Better call tree handling - including support for `prune!`.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,24 @@
 # Releases
 
+## v1.3.0
+
+  - **Breaking**: Renamed `Capture#count_for` to `Capture#retained_count_of` for better clarity and consistency.
+  - **Breaking**: Changed `CallTree#top_paths(limit)` to `CallTree#top_paths(limit:)` - now uses keyword argument.
+  - **Breaking**: Changed `CallTree#hotspots(limit)` to `CallTree#hotspots(limit:)` - now uses keyword argument.
+  - Simplified `Sampler#analyze` return structure to `{allocations: {...}, call_tree: {...}}` format.
+  - Added `Allocations#as_json` and `Allocations#to_json` methods for JSON serialization.
+  - Added `CallTree#as_json` and `CallTree#to_json` methods for JSON serialization with configurable options.
+  - `Memory::Profiler::Allocations.new` can now be instantiated directly (primarily for testing).
+  - `Sampler#statistics` is now a deprecated alias for `Sampler#analyze`.
+  - **Breaking**: Removed `Sampler#all_statistics` method.
+
+## v1.2.0
+
+  - Enable custom `depth:` and `filter:` options to `Sampler#track`.
+  - Change default filter to no-op.
+  - Add option to run GC with custom options before each sample to reduce noise.
+  - Always report sampler statistics after each sample.
+
 ## v1.1.15
 
   - Ignore `freeobj` for classes that are not being tracked.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memory-profiler
 version: !ruby/object:Gem::Version
-  version: 1.1.15
+  version: 1.3.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -56,6 +56,7 @@ files:
 - ext/memory/profiler/profiler.c
 - ext/memory/profiler/queue.h
 - lib/memory/profiler.rb
+- lib/memory/profiler/allocations.rb
 - lib/memory/profiler/call_tree.rb
 - lib/memory/profiler/capture.rb
 - lib/memory/profiler/sampler.rb