memory-profiler 1.1.2 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06ea6c4892f9d17ac8fa69ba374d2a6a94ab8b809be840b26cb544b18b529edc
-  data.tar.gz: a1c283a60721f988cac65878551eba4472a4dd889649d42b1409ba9a7b8b6756
+  metadata.gz: fdf7841a9d0249712c9bd140447e0063b5b543cae942bc1dedc09682472f3aaf
+  data.tar.gz: 14f9521f93447843b93aff1dfe15b12fce5f9491bb6a6055caf1d90cce304f17
 SHA512:
-  metadata.gz: 22a34ac3cd4ad0c0eead78deef38cd79f20f6c96338f0af5eff191a3d2f2d99ea7dc44a40993838ead2678cb52a257fbed2548e08248e5e389277801c5895cae
-  data.tar.gz: 49d267900c65e5481b6d784766e17721ba9919b984dcaf84737022622f4bbb9379773a0c98166a5d2b767192c787dd9fd13a8c43e98db3abd8d3dcb86aec74c5
+  metadata.gz: 43ba6c482b4f9e6e80e5f3213435b158b954087790e19ac4effb77fe4d06d602027c6668f63aa0b68bd592c073ac112f98735da4249d68829913d1328bb21cb4
+  data.tar.gz: b30e212a1d6a315a4fc94d9dfad066d0f1e2ec4f73dbf7f5bf757bd85e6279ddb088e87168cb6cc158b99fcb218df5ec6f3e7ca60254c8a071478959cbda4817

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/capture.c

@@ -3,6 +3,7 @@
 
 #include "capture.h"
 #include "allocations.h"
+#include "queue.h"
 
 #include "ruby.h"
 #include "ruby/debug.h"
@@ -20,6 +21,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 +40,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 +72,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 +93,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 +108,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 +149,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 +190,36 @@ 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) {
+		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;
@@ -193,19 +269,35 @@ 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) {
 			// Look up state stored during NEWOBJ
 			st_data_t state_data;
 			if (st_delete(record->object_states, (st_data_t *)&object, &state_data)) {
 				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) {
+					// Write directly to the allocated space
+					freed->klass = klass;
+					freed->allocations = allocations;
+					freed->state = state;
+					
+					// Trigger postponed job to process the queue after GC
+					rb_postponed_job_trigger(capture->postponed_job_handle);
+				}
+				// If push failed (out of memory), silently drop this freeobj event
 			}
 		}
 	}
@@ -296,6 +388,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;
 }
 

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/version.rb

@@ -7,7 +7,7 @@
 module Memory
 	# @namespace
 	module Profiler
-		VERSION = "1.1.2"
+		VERSION = "1.1.3"
 	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.3
 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