memory-profiler 1.1.2 → 1.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06ea6c4892f9d17ac8fa69ba374d2a6a94ab8b809be840b26cb544b18b529edc
-  data.tar.gz: a1c283a60721f988cac65878551eba4472a4dd889649d42b1409ba9a7b8b6756
+  metadata.gz: c70385bac57de768e1f6eb3ca9044942a357d77c97967b30636acd89b1f051f4
+  data.tar.gz: 8c7ae2a117684e61d34e09e9b2ebb4a99ab440b1b31fee364d2a92bc6caf5cac
 SHA512:
-  metadata.gz: 22a34ac3cd4ad0c0eead78deef38cd79f20f6c96338f0af5eff191a3d2f2d99ea7dc44a40993838ead2678cb52a257fbed2548e08248e5e389277801c5895cae
-  data.tar.gz: 49d267900c65e5481b6d784766e17721ba9919b984dcaf84737022622f4bbb9379773a0c98166a5d2b767192c787dd9fd13a8c43e98db3abd8d3dcb86aec74c5
+  metadata.gz: 50d848d974700ab480c805c82decf0fa58806be6f087ab4a199fa6b88963c303e459ca7a3ea2dabfea9d05bc55972edc1912917f49b46dc2752f1ea8f6d23f4b
+  data.tar.gz: 248a8fded6707058ccea2f9e1ee8eef074af4f8afeb5abfa9e786ef0e8c05efbd12fc8139eb887a156a84eaa05aba35f4dec1907426153ba935d0339198a5532

data/context/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-This guide explains how to use `memory-profiler` to detect and diagnose memory leaks in Ruby applications.
+This guide explains how to use `memory-profiler` to automatically detect and diagnose memory leaks in Ruby applications.
 
 ## Installation
 
@@ -12,218 +12,127 @@ $ bundle add memory-profiler
 
 ## Core Concepts
 
-Memory leaks happen when your application creates objects that should be garbage collected but remain referenced indefinitely. Over time, this causes memory usage to grow unbounded, eventually leading to performance degradation or out-of-memory crashes.
+Memory leaks happen when your application creates objects that should be garbage collected but remain referenced indefinitely. Over time, this causes unbounded memory growth, leading to performance degradation or crashes.
 
-`memory-profiler` helps you find memory leaks by tracking object allocations in real-time:
-
-- **{ruby Memory::Profiler::Capture}** monitors allocations using Ruby's internal NEWOBJ/FREEOBJ events.
-- **{ruby Memory::Profiler::CallTree}** aggregates allocation call paths to identify leak sources.
+- {ruby Memory::Profiler::Capture} monitors allocations using Ruby's internal NEWOBJ/FREEOBJ events.
+- {ruby Memory::Profiler::CallTree} aggregates allocation call paths to identify leak sources.
 - **No heap enumeration** - uses O(1) counters updated automatically by the VM.
 
-## Usage
-
-### Monitor Memory Growth
+## Basic Usage
 
-Start by identifying which classes are accumulating objects:
+The simplest way to detect memory leaks is to run the automatic sampler:
 
 ~~~ ruby
 require 'memory/profiler'
 
-# Create a capture instance:
-capture = Memory::Profiler::Capture.new
+# Create a sampler that monitors all allocations:
+sampler = Memory::Profiler::Sampler.new(
+	# Call stack depth for analysis:
+	depth: 10,
 
-# Start tracking all object allocations:
-capture.start
+	# Enable detailed tracking after 10 increases:
+	increases_threshold: 10
+)
 
-# Run your application code...
-run_your_app
+sampler.start
 
-# Check live object counts for common classes:
-puts "Hashes: #{capture.count_for(Hash)}"
-puts "Arrays: #{capture.count_for(Array)}"
-puts "Strings: #{capture.count_for(String)}"
+# Run periodic sampling in a background thread:
+Thread.new do
+	sampler.run(interval: 60) do |sample|
+		puts "⚠️  #{sample.target} growing: #{sample.current_size} objects (#{sample.increases} increases)"
+		
+		# After 10 increases, detailed statistics are automatically available:
+		if sample.increases >= 10
+			statistics = sampler.statistics(sample.target)
+			puts "Top leak sources:"
+			statistics[:top_paths].each do |path_data|
+				puts "  #{path_data[:count]}x from: #{path_data[:path].first}"
+			end
+		end
+	end
+end
 
-capture.stop
+# Your application runs here...
+objects = []
+while true
+	# Simulate a memory leak:
+	objects << Hash.new
+	sleep 0.1
+end
 ~~~
 
-**What this tells you**: Which object types are growing over time. If Hash count keeps increasing across multiple samples, you likely have a Hash leak.
+**What happens:**
+1. Sampler automatically tracks every class that allocates objects.
+2. Every 60 seconds, checks if any class grew significantly (>1000 objects).
+3. Reports growth via the block you provide.
+4. After 10 sustained increases, automatically captures call paths.
+5. You can then query `statistics(klass)` to find leak sources.
 
-### Find the Leak Source
+## Manual Investigation
 
-Once you've identified a leaking class, use call path analysis to find WHERE allocations come from:
+If you already know which class is leaking, you can investigate immediately:
 
 ~~~ ruby
-# Create a sampler with call path analysis:
-sampler = Memory::Profiler::Sampler.new(depth: 10)
+sampler = Memory::Profiler::Sampler.new(depth: 15)
+sampler.start
 
-# Track the leaking class with analysis:
+# Enable detailed tracking for specific class:
 sampler.track_with_analysis(Hash)
-sampler.start
 
 # Run code that triggers the leak:
-simulate_leak
+1000.times { process_request }
 
-# Analyze where allocations come from:
+# Analyze:
 statistics = sampler.statistics(Hash)
 
-puts "Live objects: #{statistics[:live_count]}"
+puts "Live Hashes: #{statistics[:live_count]}"
 puts "\nTop allocation sources:"
 statistics[:top_paths].first(5).each do |path_data|
-  puts "\n#{path_data[:count]} allocations from:"
-  path_data[:path].each { |frame| puts "  #{frame}" }
+	puts "\n#{path_data[:count]} allocations from:"
+	path_data[:path].each { |frame| puts "  #{frame}" }
 end
 
-sampler.stop
-~~~
-
-**What this shows**: The complete call stacks that led to Hash allocations. Look for unexpected paths or paths that appear repeatedly.
-
-## Real-World Example
-
-Let's say you notice your app's memory growing over time. Here's how to diagnose it:
-
-~~~ ruby
-require 'memory/profiler'
-
-# Setup monitoring:
-capture = Memory::Profiler::Capture.new
-capture.start
-
-# Take baseline measurement:
-GC.start  # Clean up old objects first
-baseline = {
-  hashes: capture.count_for(Hash),
-  arrays: capture.count_for(Array),
-  strings: capture.count_for(String)
-}
-
-# Run your application for a period:
-# In production: sample periodically (every 60 seconds)
-# In development: run through typical workflows
-sleep 60
-
-# Check what grew:
-current = {
-  hashes: capture.count_for(Hash),
-  arrays: capture.count_for(Array),
-  strings: capture.count_for(String)
-}
-
-# Report growth:
-current.each do |type, count|
-  growth = count - baseline[type]
-  if growth > 100
-    puts "⚠️  #{type} grew by #{growth} objects"
-  end
+puts "\nHotspot frames:"
+statistics[:hotspots].first(5).each do |location, count|
+	puts "  #{location}: #{count}"
 end
 
-capture.stop
+sampler.stop!
 ~~~
 
-If Hashes grew significantly, enable detailed tracking:
-
-~~~ ruby
-# Create detailed sampler:
-sampler = Memory::Profiler::Sampler.new(depth: 15)
-sampler.track_with_analysis(Hash)
-sampler.start
-
-# Run suspicious code path:
-process_user_requests(1000)
-
-# Find the culprits:
-statistics = sampler.statistics(Hash)
-statistics[:top_paths].first(3).each_with_index do |path_data, i|
-  puts "\n#{i+1}. #{path_data[:count]} Hash allocations:"
-  path_data[:path].first(5).each { |frame| puts "     #{frame}" }
-end
-
-sampler.stop
-~~~
-
-## Best Practices
-
-### When Tracking in Production
-
-1. **Start tracking AFTER startup**: Call `GC.start` before `capture.start` to avoid counting initialization objects
-2. **Use count-only mode for monitoring**: `capture.track(Hash)` (no callback) has minimal overhead
-3. **Enable analysis only when investigating**: Call path analysis has higher overhead
-4. **Sample periodically**: Take measurements every 60 seconds rather than continuously
-5. **Stop when done**: Always call `stop()` to remove event hooks
-
-### Performance Considerations
-
-**Count-only tracking** (no callback):
-- Minimal overhead (~5-10% on allocation hotpath)
-- Safe for production monitoring
-- Tracks all classes automatically
-
-**Call path analysis** (with callback):
-- Higher overhead (captures `caller_locations` on every allocation)  
-- Use during investigation, not continuous monitoring
-- Only track specific classes you're investigating
-
-### Avoiding False Positives
-
-Objects allocated before tracking starts but freed after will show as negative or zero:
-
-~~~ ruby
-# ❌ Wrong - counts existing objects:
-capture.start
-100.times { {} }
-GC.start  # Frees old + new objects → underflow
-
-# ✅ Right - clean slate first:
-GC.start  # Clear old objects
-capture.start
-100.times { {} }
-~~~
-
-## Common Scenarios
-
-### Detecting Cache Leaks
-
-~~~ ruby
-# Monitor your cache class:
-capture = Memory::Profiler::Capture.new
-capture.start
-
-cache_baseline = capture.count_for(CacheEntry)
-
-# Run for a period:
-sleep 300  # 5 minutes
-
-cache_current = capture.count_for(CacheEntry)
-
-if cache_current > cache_baseline * 2
-  puts "⚠️  Cache is leaking! #{cache_current - cache_baseline} entries added"
-  # Enable detailed tracking to find the source
-end
-~~~
-
-### Finding Retention in Request Processing
-
-~~~ ruby
-# Track during request processing:
-sampler = Memory::Profiler::Sampler.new
-sampler.track_with_analysis(Hash)
-sampler.start
-
-# Process requests:
-1000.times do
-  process_request
-end
-
-# Check if Hashes are being retained:
-statistics = sampler.statistics(Hash)
-
-if statistics[:live_count] > 1000
-  puts "Leaking #{statistics[:live_count]} Hashes per 1000 requests!"
-  statistics[:top_paths].first(3).each do |path_data|
-    puts "\n#{path_data[:count]}x from:"
-    puts path_data[:path].join("\n  ")
-  end
-end
-
-sampler.stop
-~~~
+## Understanding the Output
+
+**Sample data** (from growth detection):
+- `target`: The class showing growth
+- `current_size`: Current live object count
+- `increases`: Number of sustained growth events (>1000 objects each)
+- `threshold`: Minimum growth to trigger an increase
+
+**Statistics** (after detailed tracking enabled):
+- `live_count`: Current retained objects
+- `top_paths`: Complete call stacks ranked by allocation frequency
+- `hotspots`: Individual frames aggregated across all paths
+
+**Top paths** show WHERE objects are created:
+```
+50 allocations from:
+	app/services/processor.rb:45:in 'process_item'
+	app/workers/job.rb:23:in 'perform'
+```
+
+**Hotspots** show which lines appear most across all paths:
+```
+app/services/processor.rb:45: 150    ← This line in many different call stacks
+```
+
+## Performance Considerations
+
+**Automatic mode** (recommended for production):
+- Minimal overhead initially (just counting).
+- Detailed tracking only enabled when leaks detected.
+- 60-second sampling interval is non-intrusive.
+
+**Manual tracking** (for investigation):
+- Higher overhead (captures `caller_locations` on every allocation).
+- Use during debugging, not continuous monitoring.
+- Only track specific classes you're investigating.

data/context/index.yaml

@@ -8,5 +8,9 @@ metadata:
 files:
 - path: getting-started.md
   title: Getting Started
-  description: This guide explains how to use `memory-profiler` to detect and diagnose
-    memory leaks in Ruby applications.
+  description: This guide explains how to use `memory-profiler` to automatically detect
+    and diagnose memory leaks in Ruby applications.
+- path: rack-integration.md
+  title: Rack Integration
+  description: This guide explains how to integrate `memory-profiler` into Rack applications
+    for automatic memory leak detection.

data/context/rack-integration.md

@@ -0,0 +1,70 @@
+# Rack Integration
+
+This guide explains how to integrate `memory-profiler` into Rack applications for automatic memory leak detection.
+
+## Overview
+
+The Rack middleware pattern provides a clean way to add memory monitoring to your application. The sampler runs in a background thread, automatically detecting leaks without impacting request processing.
+
+## Basic Middleware
+
+Create a middleware that monitors memory in the background:
+
+~~~ ruby
+# app/middleware/memory_monitoring.rb
+require 'console'
+require 'memory/profiler'
+
+class MemoryMonitoring
+	def initialize(app)
+		@app = app
+		
+		# Create sampler with automatic leak detection:
+		@sampler = Memory::Profiler::Sampler.new(
+			# Use up to 10 caller locations for leak call graph analysis:
+			depth: 10,
+			# Enable detailed tracking after 10 increases:
+			increases_threshold: 10
+		)
+		
+		@sampler.start
+		Console.info("Memory monitoring enabled")
+		
+		# Background thread runs periodic sampling:
+		@thread = Thread.new do
+			@sampler.run(interval: 60) do |sample|
+				Console.warn(sample.target, "Memory usage increased!", sample: sample)
+				
+				# After threshold, get leak sources:
+				if sample.increases >= 10
+					if statistics = @sampler.statistics(sample.target)
+						Console.error(sample.target, "Memory leak analysis:", statistics: statistics)
+					end
+				end
+			end
+		end
+	end
+	
+	def call(env)
+		@app.call(env)
+	end
+	
+	def shutdown
+		@thread&.kill
+		@sampler&.stop!
+	end
+end
+~~~
+
+## Adding to config.ru
+
+Add the middleware to your Rack application:
+
+~~~ ruby
+# config.ru
+require_relative 'app/middleware/memory_monitoring'
+
+use MemoryMonitoring
+
+run YourApp
+~~~

data/ext/memory/profiler/allocations.c

@@ -12,8 +12,9 @@ static VALUE Memory_Profiler_Allocations = Qnil;
 
 // Helper to mark object_states table values
 static int Memory_Profiler_Allocations_object_states_mark(st_data_t key, st_data_t value, st_data_t arg) {
-	VALUE object = (VALUE)key;
-	rb_gc_mark_movable(object);
+	// Don't mark the object, we use it as a key but we never use it as an object, and we don't want to retain it.
+	// VALUE object = (VALUE)key;
+	// rb_gc_mark_movable(object);
 
 	VALUE state = (VALUE)value;
 	if (!NIL_P(state)) {

data/ext/memory/profiler/capture.c

@@ -3,6 +3,7 @@
 
 #include "capture.h"
 #include "allocations.h"
+#include "queue.h"
 
 #include "ruby.h"
 #include "ruby/debug.h"
@@ -12,6 +13,8 @@
 
 enum {
 	DEBUG = 0,
+	DEBUG_FREED_QUEUE = 0,
+	DEBUG_STATE = 0,
 };
 
 static VALUE Memory_Profiler_Capture = Qnil;
@@ -20,6 +23,18 @@ static VALUE Memory_Profiler_Capture = Qnil;
 static VALUE sym_newobj;
 static VALUE sym_freeobj;
 
+// Queue item - freed object data to be processed after GC
+struct Memory_Profiler_Queue_Item {
+	// The class of the freed object:
+	VALUE klass;
+
+	// The Allocations wrapper:
+	VALUE allocations;
+
+	// The state returned from callback on newobj:
+	VALUE state;
+};
+
 // Main capture state
 struct Memory_Profiler_Capture {
 	// class => VALUE (wrapped Memory_Profiler_Capture_Allocations).
@@ -27,6 +42,12 @@ struct Memory_Profiler_Capture {
 
 	// Is tracking enabled (via start/stop):
 	int enabled;
+	
+	// Queue for freed objects (processed after GC via postponed job)
+	struct Memory_Profiler_Queue freed_queue;
+	
+	// Handle for the postponed job
+	rb_postponed_job_handle_t postponed_job_handle;
 };
 
 // GC mark callback for tracked_classes table
@@ -53,6 +74,17 @@ static void Memory_Profiler_Capture_mark(void *ptr) {
 	if (capture->tracked_classes) {
 		st_foreach(capture->tracked_classes, Memory_Profiler_Capture_tracked_classes_mark, 0);
 	}
+	
+	// Mark freed objects in the queue:
+	for (size_t i = 0; i < capture->freed_queue.count; i++) {
+		struct Memory_Profiler_Queue_Item *freed = Memory_Profiler_Queue_at(&capture->freed_queue, i);
+		rb_gc_mark_movable(freed->klass);
+		rb_gc_mark_movable(freed->allocations);
+
+		if (freed->state) {
+			rb_gc_mark_movable(freed->state);
+		}
+	}
 }
 
 // GC free function
@@ -63,6 +95,9 @@ static void Memory_Profiler_Capture_free(void *ptr) {
 		st_free_table(capture->tracked_classes);
 	}
 	
+	// Free the queue (elements are stored directly, just free the queue)
+	Memory_Profiler_Queue_free(&capture->freed_queue);
+	
 	xfree(capture);
 }
 
@@ -75,6 +110,9 @@ static size_t Memory_Profiler_Capture_memsize(const void *ptr) {
 		size += capture->tracked_classes->num_entries * (sizeof(st_data_t) + sizeof(struct Memory_Profiler_Capture_Allocations));
 	}
 	
+	// Add size of freed queue (elements stored directly)
+	size += capture->freed_queue.capacity * capture->freed_queue.element_size;
+	
 	return size;
 }
 
@@ -113,6 +151,16 @@ static void Memory_Profiler_Capture_compact(void *ptr) {
 			rb_raise(rb_eRuntimeError, "tracked_classes modified during GC compaction");
 		}
 	}
+	
+	// Update freed objects in the queue
+	for (size_t i = 0; i < capture->freed_queue.count; i++) {
+		struct Memory_Profiler_Queue_Item *freed = Memory_Profiler_Queue_at(&capture->freed_queue, i);
+		
+		// Update all VALUEs if they moved during compaction
+		freed->klass = rb_gc_location(freed->klass);
+		freed->allocations = rb_gc_location(freed->allocations);
+		freed->state = rb_gc_location(freed->state);
+	}
 }
 
 static const rb_data_type_t Memory_Profiler_Capture_type = {
@@ -144,6 +192,34 @@ const char *event_flag_name(rb_event_flag_t event_flag) {
 	}
 }
 
+// Postponed job callback - processes queued freed objects
+// This runs after GC completes, when it's safe to call Ruby code
+static void Memory_Profiler_Capture_process_freed_queue(void *arg) {
+	VALUE self = (VALUE)arg;
+	struct Memory_Profiler_Capture *capture;
+	TypedData_Get_Struct(self, struct Memory_Profiler_Capture, &Memory_Profiler_Capture_type, capture);
+	
+	if (DEBUG_FREED_QUEUE) fprintf(stderr, "Processing freed queue with %zu entries\n", capture->freed_queue.count);
+	
+	// Process all freed objects in the queue
+	for (size_t i = 0; i < capture->freed_queue.count; i++) {
+		struct Memory_Profiler_Queue_Item *freed = Memory_Profiler_Queue_at(&capture->freed_queue, i);
+		VALUE klass = freed->klass;
+		VALUE allocations = freed->allocations;
+		VALUE state = freed->state;
+		
+		struct Memory_Profiler_Capture_Allocations *record = Memory_Profiler_Allocations_get(allocations);
+		
+		// Call the Ruby callback with (klass, :freeobj, state)
+		if (!NIL_P(record->callback)) {
+			rb_funcall(record->callback, rb_intern("call"), 3, klass, sym_freeobj, state);
+		}
+	}
+	
+	// Clear the queue (elements are reused on next cycle)
+	Memory_Profiler_Queue_clear(&capture->freed_queue);
+}
+
 // Handler for NEWOBJ event
 static void Memory_Profiler_Capture_newobj_handler(VALUE self, struct Memory_Profiler_Capture *capture, VALUE klass, VALUE object) {
 	st_data_t allocations_data;
@@ -168,6 +244,9 @@ static void Memory_Profiler_Capture_newobj_handler(VALUE self, struct Memory_Pro
 				if (!record->object_states) {
 					record->object_states = st_init_numtable();
 				}
+				
+				if (DEBUG_STATE) fprintf(stderr, "Memory_Profiler_Capture_newobj_handler: Inserting state for object: %p (%s)\n", (void *)object, rb_class2name(klass));
+
 				st_insert(record->object_states, (st_data_t)object, (st_data_t)state);
 				// Notify GC about the state VALUE stored in the table
 				RB_OBJ_WRITTEN(self, Qnil, state);
@@ -193,19 +272,42 @@ static void Memory_Profiler_Capture_newobj_handler(VALUE self, struct Memory_Pro
 }
 
 // Handler for FREEOBJ event
+// CRITICAL: This runs during GC when no Ruby code can be executed!
+// We MUST NOT call rb_funcall or any Ruby code here - just queue the work.
 static void Memory_Profiler_Capture_freeobj_handler(VALUE self, struct Memory_Profiler_Capture *capture, VALUE klass, VALUE object) {
 	st_data_t allocations_data;
 	if (st_lookup(capture->tracked_classes, (st_data_t)klass, &allocations_data)) {
 		VALUE allocations = (VALUE)allocations_data;
 		struct Memory_Profiler_Capture_Allocations *record = Memory_Profiler_Allocations_get(allocations);
 		record->free_count++;
+		
+		// If we have a callback and detailed tracking, queue the freeobj for later processing
 		if (!NIL_P(record->callback) && record->object_states) {
+			if (DEBUG_STATE) fprintf(stderr, "Memory_Profiler_Capture_freeobj_handler: Looking up state for object: %p\n", (void *)object);
+
 			// Look up state stored during NEWOBJ
 			st_data_t state_data;
 			if (st_delete(record->object_states, (st_data_t *)&object, &state_data)) {
+				if (DEBUG_STATE) fprintf(stderr, "Found state for object: %p\n", (void *)object);
 				VALUE state = (VALUE)state_data;
-				// Call with (klass, :freeobj, state)
-				rb_funcall(record->callback, rb_intern("call"), 3, klass, sym_freeobj, state);
+				
+				// Push a new item onto the queue (returns pointer to write to)
+				// NOTE: realloc is safe during GC (doesn't trigger Ruby allocation)
+				struct Memory_Profiler_Queue_Item *freed = Memory_Profiler_Queue_push(&capture->freed_queue);
+				if (freed) {
+					if (DEBUG_FREED_QUEUE) fprintf(stderr, "Queued freed object, queue size now: %zu/%zu\n", capture->freed_queue.count, capture->freed_queue.capacity);
+					// Write directly to the allocated space
+					freed->klass = klass;
+					freed->allocations = allocations;
+					freed->state = state;
+					
+					// Trigger postponed job to process the queue after GC
+					if (DEBUG_FREED_QUEUE) fprintf(stderr, "Triggering postponed job to process the queue after GC\n");
+					rb_postponed_job_trigger(capture->postponed_job_handle);
+				} else {
+					if (DEBUG_FREED_QUEUE) fprintf(stderr, "Failed to queue freed object, out of memory\n");
+				}
+				// If push failed (out of memory), silently drop this freeobj event
 			}
 		}
 	}
@@ -266,7 +368,12 @@ static void Memory_Profiler_Capture_event_callback(VALUE data, void *ptr) {
 	if (!klass) return;
 	
 	if (DEBUG) {
-		const char *klass_name = rb_class2name(klass);
+		// In events other than NEWOBJ, we are unable to allocate objects (due to GC), so we simply say "ignored":
+		const char *klass_name = "ignored";
+		if (event_flag == RUBY_INTERNAL_EVENT_NEWOBJ) {
+			klass_name = rb_class2name(klass);
+		}
+		
 		fprintf(stderr, "Memory_Profiler_Capture_event_callback: %s, Object: %p, Class: %p (%s)\n", event_flag_name(event_flag), (void *)object, (void *)klass, klass_name);
 	}
 	
@@ -296,6 +403,21 @@ static VALUE Memory_Profiler_Capture_alloc(VALUE klass) {
 	
 	capture->enabled = 0;
 	
+	// Initialize the freed object queue
+	Memory_Profiler_Queue_initialize(&capture->freed_queue, sizeof(struct Memory_Profiler_Queue_Item));
+	
+	// Pre-register the postponed job for processing freed objects
+	// The job will be triggered whenever we queue freed objects during GC
+	capture->postponed_job_handle = rb_postponed_job_preregister(
+		0, // flags
+		Memory_Profiler_Capture_process_freed_queue,
+		(void *)obj
+	);
+	
+	if (capture->postponed_job_handle == POSTPONED_JOB_HANDLE_INVALID) {
+		rb_raise(rb_eRuntimeError, "Failed to register postponed job!");
+	}
+	
 	return obj;
 }
 
@@ -342,6 +464,7 @@ static VALUE Memory_Profiler_Capture_stop(VALUE self) {
 // Add a class to track with optional callback
 // Usage: track(klass) or track(klass) { |obj, klass| ... }
 // Callback can call caller_locations with desired depth
+// Returns the Allocations object for the tracked class
 static VALUE Memory_Profiler_Capture_track(int argc, VALUE *argv, VALUE self) {
 	struct Memory_Profiler_Capture *capture;
 	TypedData_Get_Struct(self, struct Memory_Profiler_Capture, &Memory_Profiler_Capture_type, capture);
@@ -350,8 +473,10 @@ static VALUE Memory_Profiler_Capture_track(int argc, VALUE *argv, VALUE self) {
 	rb_scan_args(argc, argv, "1&", &klass, &callback);
 		
 	st_data_t allocations_data;
+	VALUE allocations;
+	
 	if (st_lookup(capture->tracked_classes, (st_data_t)klass, &allocations_data)) {
-		VALUE allocations = (VALUE)allocations_data;
+		allocations = (VALUE)allocations_data;
 		struct Memory_Profiler_Capture_Allocations *record = Memory_Profiler_Allocations_get(allocations);
 		RB_OBJ_WRITE(self, &record->callback, callback);
 	} else {
@@ -362,7 +487,7 @@ static VALUE Memory_Profiler_Capture_track(int argc, VALUE *argv, VALUE self) {
 		record->object_states = NULL;
 		
 		// Wrap the record in a VALUE
-		VALUE allocations = Memory_Profiler_Allocations_wrap(record);
+		allocations = Memory_Profiler_Allocations_wrap(record);
 		
 		st_insert(capture->tracked_classes, (st_data_t)klass, (st_data_t)allocations);
 		// Notify GC about the class VALUE stored as key in the table
@@ -375,7 +500,7 @@ static VALUE Memory_Profiler_Capture_track(int argc, VALUE *argv, VALUE self) {
 		}
 	}
 	
-	return self;
+	return allocations;
 }
 
 // Stop tracking a class
@@ -465,6 +590,19 @@ static VALUE Memory_Profiler_Capture_each(VALUE self) {
 	return self;
 }
 
+// Get allocations for a specific class
+static VALUE Memory_Profiler_Capture_aref(VALUE self, VALUE klass) {
+	struct Memory_Profiler_Capture *capture;
+	TypedData_Get_Struct(self, struct Memory_Profiler_Capture, &Memory_Profiler_Capture_type, capture);
+	
+	st_data_t allocations_data;
+	if (st_lookup(capture->tracked_classes, (st_data_t)klass, &allocations_data)) {
+		return (VALUE)allocations_data;
+	}
+	
+	return Qnil;
+}
+
 void Init_Memory_Profiler_Capture(VALUE Memory_Profiler)
 {
 	// Initialize event symbols
@@ -484,6 +622,7 @@ void Init_Memory_Profiler_Capture(VALUE Memory_Profiler)
 	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, "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);
 	
 	// Initialize Allocations class

data/ext/memory/profiler/queue.h

@@ -0,0 +1,122 @@
+// Released under the MIT License.
+// Copyright, 2025, by Samuel Williams.
+
+// Provides a simple queue for storing elements directly (not as pointers).
+// Elements are enqueued during GC and batch-processed afterward.
+
+#pragma once
+
+#include <stdlib.h>
+#include <string.h>
+#include <assert.h>
+
+static const size_t MEMORY_PROFILER_QUEUE_DEFAULT_COUNT = 128;
+
+struct Memory_Profiler_Queue {
+	// The queue storage (elements stored directly, not as pointers):
+	void *base;
+	
+	// The allocated capacity (number of elements):
+	size_t capacity;
+	
+	// The number of used elements:
+	size_t count;
+	
+	// The size of each element in bytes:
+	size_t element_size;
+};
+
+// Initialize an empty queue
+inline static void Memory_Profiler_Queue_initialize(struct Memory_Profiler_Queue *queue, size_t element_size)
+{
+	queue->base = NULL;
+	queue->capacity = 0;
+	queue->count = 0;
+	queue->element_size = element_size;
+}
+
+// Free the queue and its contents
+inline static void Memory_Profiler_Queue_free(struct Memory_Profiler_Queue *queue)
+{
+	if (queue->base) {
+		free(queue->base);
+		queue->base = NULL;
+	}
+	
+	queue->capacity = 0;
+	queue->count = 0;
+}
+
+// Resize the queue to have at least the given capacity
+inline static int Memory_Profiler_Queue_resize(struct Memory_Profiler_Queue *queue, size_t required_capacity)
+{
+	if (required_capacity <= queue->capacity) {
+		// Already big enough:
+		return 0;
+	}
+	
+	size_t new_capacity = queue->capacity;
+	
+	// If the queue is empty, we need to set the initial size:
+	if (new_capacity == 0) {
+		new_capacity = MEMORY_PROFILER_QUEUE_DEFAULT_COUNT;
+	}
+	
+	// Double until we reach required capacity
+	while (new_capacity < required_capacity) {
+		// Check for overflow
+		if (new_capacity > (SIZE_MAX / (2 * queue->element_size))) {
+			return -1; // Would overflow
+		}
+		new_capacity *= 2;
+	}
+	
+	// Check final size doesn't overflow
+	if (new_capacity > (SIZE_MAX / queue->element_size)) {
+		return -1; // Too large
+	}
+	
+	// Reallocate
+	void *new_base = realloc(queue->base, new_capacity * queue->element_size);
+	if (new_base == NULL) {
+		return -1; // Allocation failed
+	}
+	
+	queue->base = new_base;
+	queue->capacity = new_capacity;
+	
+	return 1; // Success
+}
+
+// Push a new element onto the end of the queue, returning pointer to the allocated space
+// WARNING: The returned pointer is only valid until the next push operation
+inline static void* Memory_Profiler_Queue_push(struct Memory_Profiler_Queue *queue)
+{
+	// Ensure we have capacity
+	size_t new_count = queue->count + 1;
+	if (new_count > queue->capacity) {
+		if (Memory_Profiler_Queue_resize(queue, new_count) == -1) {
+			return NULL;
+		}
+	}
+	
+	// Calculate pointer to the new element
+	void *element = (char*)queue->base + (queue->count * queue->element_size);
+	queue->count++;
+	
+	return element;
+}
+
+// Clear the queue (reset count to 0, reusing allocated memory)
+inline static void Memory_Profiler_Queue_clear(struct Memory_Profiler_Queue *queue)
+{
+	queue->count = 0;
+}
+
+// Get element at index (for iteration)
+// WARNING: Do not hold these pointers across push operations
+inline static void* Memory_Profiler_Queue_at(struct Memory_Profiler_Queue *queue, size_t index)
+{
+	assert(index < queue->count);
+	return (char*)queue->base + (index * queue->element_size);
+}

data/lib/memory/profiler/sampler.rb

@@ -141,7 +141,7 @@ module Memory
 					if sample.sample!(count)
 						# Check if we should enable detailed tracking
 						if sample.increases >= @increases_threshold && !@call_trees.key?(klass)
-							track_with_analysis_internal(klass, allocations)
+							track(klass, allocations)
 						end
 						
 						# Notify about growth if block given
@@ -150,13 +150,19 @@ module Memory
 				end
 			end
 			
-			# Internal: Enable tracking with analysis using allocations object
-			private def track_with_analysis_internal(klass, allocations)
+			# Start tracking with call path analysis.
+			#
+			# @parameter klass [Class] The class to track with detailed analysis.
+			def track(klass, allocations = nil)
+				# 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 with new signature:
+				# 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|
@@ -166,43 +172,16 @@ module Memory
 						locations = caller_locations(1, depth)
 						filtered = locations.select(&filter)
 						unless filtered.empty?
-							# Record returns the leaf node - return it so C can store it
+							# Record returns the leaf node - return it so C can store it:
 							tree.record(filtered)
 						end
-						# Return nil or the node - C will store whatever we return
+						# Return nil or the node - C will store whatever we return.
 					when :freeobj
-						# Decrement using the state (leaf node) passed back from C
-						if state
-							state.decrement_path!
-						end
+						# Decrement using the state (leaf node) passed back from then native extension:
+						state&.decrement_path!
 					end
 				rescue Exception => error
-					warn "Error in track_with_analysis_internal: #{error.message}\n#{error.backtrace.join("\n")}"
-				end
-			end
-			
-			# Start tracking allocations for a class (count only).
-			def track(klass)
-				return if @capture.tracking?(klass)
-				
-				@capture.track(klass)
-			end
-			
-			# Start tracking with call path analysis.
-			#
-			# @parameter klass [Class] The class to track with detailed analysis.
-			def track_with_analysis(klass)
-				# Track the class if not already tracked
-				unless @capture.tracking?(klass)
-					@capture.track(klass)
-				end
-				
-				# Enable analysis by setting callback on the allocations object
-				@capture.each do |tracked_klass, allocations|
-					if tracked_klass == klass
-						track_with_analysis_internal(klass, allocations)
-						break
-					end
+					warn "Error in allocation tracking: #{error.message}\n#{error.backtrace.join("\n")}"
 				end
 			end
 			
@@ -280,11 +259,7 @@ module Memory
 			private
 			
 			def default_filter
-				->(location) {path = location.path
-																		!path.include?("/gems/") && 
-																							!path.include?("/ruby/") &&
-																							!path.start_with?("(eval)")
-				}
+				->(location) {!location.path.match?(%r{/(gems|ruby)/|\A\(eval\)})}
 			end
 		end
 	end

data/lib/memory/profiler/version.rb

@@ -7,7 +7,7 @@
 module Memory
 	# @namespace
 	module Profiler
-		VERSION = "1.1.2"
+		VERSION = "1.1.4"
 	end
 end
 

data/readme.md

@@ -9,14 +9,14 @@ Efficient memory allocation tracking focused on **retained objects only**. Autom
   - **Retained Objects Only**: Uses `RUBY_INTERNAL_EVENT_NEWOBJ` and `RUBY_INTERNAL_EVENT_FREEOBJ` to automatically track only objects that survive GC.
   - **O(1) Live Counts**: Maintains per-class counters updated on alloc/free - no heap enumeration needed\!
   - **Tree-Based Analysis**: Deduplicates common call paths using an efficient tree structure.
-  - **Native C Extension**: **Required** - uses Ruby internal events not available in pure Ruby.
-  - **Configurable Depth**: Control how deep to capture call stacks.
 
 ## Usage
 
 Please see the [project documentation](https://socketry.github.io/memory-profiler/) for more details.
 
-  - [Getting Started](https://socketry.github.io/memory-profiler/guides/getting-started/index) - This guide explains how to use `memory-profiler` to detect and diagnose memory leaks in Ruby applications.
+  - [Getting Started](https://socketry.github.io/memory-profiler/guides/getting-started/index) - This guide explains how to use `memory-profiler` to automatically detect and diagnose memory leaks in Ruby applications.
+
+  - [Rack Integration](https://socketry.github.io/memory-profiler/guides/rack-integration/index) - This guide explains how to integrate `memory-profiler` into Rack applications for automatic memory leak detection.
 
 ## Releases
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memory-profiler
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.4
 platform: ruby
 authors:
 - Samuel Williams
@@ -45,12 +45,14 @@ extra_rdoc_files: []
 files:
 - context/getting-started.md
 - context/index.yaml
+- context/rack-integration.md
 - ext/extconf.rb
 - ext/memory/profiler/allocations.c
 - ext/memory/profiler/allocations.h
 - ext/memory/profiler/capture.c
 - ext/memory/profiler/capture.h
 - ext/memory/profiler/profiler.c
+- ext/memory/profiler/queue.h
 - lib/memory/profiler.rb
 - lib/memory/profiler/call_tree.rb
 - lib/memory/profiler/capture.rb
@@ -72,7 +74,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="