memory-profiler 1.1.1 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e818941dde11b9247c4451e48d59ded21116b7cbcd40d1885b200f9124a1adf4
-  data.tar.gz: 1ad6e8a133b29d3fa6011c5f21c5b15dca3a2b1f3c8839f5294bce46a578d82e
+  metadata.gz: fdf7841a9d0249712c9bd140447e0063b5b543cae942bc1dedc09682472f3aaf
+  data.tar.gz: 14f9521f93447843b93aff1dfe15b12fce5f9491bb6a6055caf1d90cce304f17
 SHA512:
-  metadata.gz: f8d61cf642ed4fd9d0b0f6ceae5f3e09f53351df3f134245870edce7d1fbc7eea2ca82b87aa92abc9d7308444a4a0be5aaadadb4d7d613840e05ec34df022117
-  data.tar.gz: d67925a5753683b75eca7b49a861038cb28d52a537a04c459cb8808ddcb1c582f3512ecccbd922bd31f649101f3b726f3e60c5e6f5cf3072f25b5ee2a55e5a77
+  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/extconf.rb

@@ -16,7 +16,7 @@ if ENV.key?("RUBY_DEBUG")
 	append_cflags(["-DRUBY_DEBUG", "-O0"])
 end
 
-$srcs = ["memory/profiler/profiler.c", "memory/profiler/capture.c"]
+$srcs = ["memory/profiler/profiler.c", "memory/profiler/capture.c", "memory/profiler/allocations.c"]
 $VPATH << "$(srcdir)/memory/profiler"
 
 # Check for required headers

data/ext/memory/profiler/allocations.c

@@ -0,0 +1,179 @@
+// Released under the MIT License.
+// Copyright, 2025, by Samuel Williams.
+
+#include "allocations.h"
+
+#include "ruby.h"
+#include "ruby/debug.h"
+#include "ruby/st.h"
+#include <stdio.h>
+
+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);
+
+	VALUE state = (VALUE)value;
+	if (!NIL_P(state)) {
+		rb_gc_mark_movable(state);
+	}
+	return ST_CONTINUE;
+}
+
+// Foreach callback for st_foreach_with_replace (iteration logic)
+static int Memory_Profiler_Allocations_object_states_foreach(st_data_t key, st_data_t value, st_data_t argp, int error) {
+	// Return ST_REPLACE to trigger the replace callback for each entry
+	return ST_REPLACE;
+}
+
+// Replace callback for st_foreach_with_replace to update object_states keys and values during compaction
+static int Memory_Profiler_Allocations_object_states_compact(st_data_t *key, st_data_t *value, st_data_t data, int existing) {
+	VALUE old_object = (VALUE)*key;
+	VALUE old_state = (VALUE)*value;
+	
+	VALUE new_object = rb_gc_location(old_object);
+	VALUE new_state = rb_gc_location(old_state);
+	
+	// Update key if it moved
+	if (old_object != new_object) {
+		*key = (st_data_t)new_object;
+	}
+	
+	// Update value if it moved
+	if (old_state != new_state) {
+		*value = (st_data_t)new_state;
+	}
+	
+	return ST_CONTINUE;
+}
+
+// GC mark function for Allocations
+static void Memory_Profiler_Allocations_mark(void *ptr) {
+	struct Memory_Profiler_Capture_Allocations *record = ptr;
+	
+	if (!record) {
+		return;
+	}
+	
+	if (!NIL_P(record->callback)) {
+		rb_gc_mark_movable(record->callback);
+	}
+	
+	// Mark object_states table if it exists
+	if (record->object_states) {
+		st_foreach(record->object_states, Memory_Profiler_Allocations_object_states_mark, 0);
+	}
+}
+
+// GC free function for Allocations
+static void Memory_Profiler_Allocations_free(void *ptr) {
+	struct Memory_Profiler_Capture_Allocations *record = ptr;
+	
+	if (record->object_states) {
+		st_free_table(record->object_states);
+	}
+	
+	xfree(record);
+}
+
+// GC compact function for Allocations
+static void Memory_Profiler_Allocations_compact(void *ptr) {
+	struct Memory_Profiler_Capture_Allocations *record = ptr;
+	
+	// Update callback if it moved
+	if (!NIL_P(record->callback)) {
+		record->callback = rb_gc_location(record->callback);
+	}
+	
+	// Update object_states table if it exists
+	if (record->object_states && record->object_states->num_entries > 0) {
+		if (st_foreach_with_replace(record->object_states, Memory_Profiler_Allocations_object_states_foreach, Memory_Profiler_Allocations_object_states_compact, 0)) {
+			rb_raise(rb_eRuntimeError, "object_states modified during GC compaction");
+		}
+	}
+}
+
+static const rb_data_type_t Memory_Profiler_Allocations_type = {
+	"Memory::Profiler::Allocations",
+	{
+		.dmark = Memory_Profiler_Allocations_mark,
+		.dcompact = Memory_Profiler_Allocations_compact,
+		.dfree = Memory_Profiler_Allocations_free,
+	},
+	0, 0, RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED
+};
+
+// Wrap an allocations record
+VALUE Memory_Profiler_Allocations_wrap(struct Memory_Profiler_Capture_Allocations *record) {
+	return TypedData_Wrap_Struct(Memory_Profiler_Allocations, &Memory_Profiler_Allocations_type, record);
+}
+
+// Get allocations record from wrapper
+struct Memory_Profiler_Capture_Allocations* Memory_Profiler_Allocations_get(VALUE self) {
+	struct Memory_Profiler_Capture_Allocations *record;
+	TypedData_Get_Struct(self, struct Memory_Profiler_Capture_Allocations, &Memory_Profiler_Allocations_type, record);
+	return record;
+}
+
+// Allocations#new_count
+static VALUE Memory_Profiler_Allocations_new_count(VALUE self) {
+	struct Memory_Profiler_Capture_Allocations *record = Memory_Profiler_Allocations_get(self);
+	return SIZET2NUM(record->new_count);
+}
+
+// Allocations#free_count
+static VALUE Memory_Profiler_Allocations_free_count(VALUE self) {
+	struct Memory_Profiler_Capture_Allocations *record = Memory_Profiler_Allocations_get(self);
+	return SIZET2NUM(record->free_count);
+}
+
+// Allocations#retained_count
+static VALUE Memory_Profiler_Allocations_retained_count(VALUE self) {
+	struct Memory_Profiler_Capture_Allocations *record = Memory_Profiler_Allocations_get(self);
+	// Handle underflow when free_count > new_count
+	size_t retained = record->free_count > record->new_count ? 0 : record->new_count - record->free_count;
+	return SIZET2NUM(retained);
+}
+
+// Allocations#track { |klass| ... }
+static VALUE Memory_Profiler_Allocations_track(int argc, VALUE *argv, VALUE self) {
+	struct Memory_Profiler_Capture_Allocations *record = Memory_Profiler_Allocations_get(self);
+	
+	VALUE callback;
+	rb_scan_args(argc, argv, "&", &callback);
+	
+	// Use write barrier - self (Allocations wrapper) keeps Capture alive, which keeps callback alive
+	RB_OBJ_WRITE(self, &record->callback, callback);
+	
+	return self;
+}
+
+// Clear/reset allocation counts and state for a record
+void Memory_Profiler_Allocations_clear(VALUE allocations) {
+	struct Memory_Profiler_Capture_Allocations *record = Memory_Profiler_Allocations_get(allocations);
+	record->new_count = 0;   // Reset allocation count
+	record->free_count = 0;  // Reset free count
+	RB_OBJ_WRITE(allocations, &record->callback, Qnil); // Clear callback with write barrier
+	
+	// Clear object states
+	if (record->object_states) {
+		st_free_table(record->object_states);
+		record->object_states = NULL;
+	}
+}
+
+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);
+	
+	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);
+	rb_define_method(Memory_Profiler_Allocations, "retained_count", Memory_Profiler_Allocations_retained_count, 0);
+	rb_define_method(Memory_Profiler_Allocations, "track", Memory_Profiler_Allocations_track, -1);  // -1 to accept block
+}

data/ext/memory/profiler/allocations.h

@@ -0,0 +1,31 @@
+// Released under the MIT License.
+// Copyright, 2025, by Samuel Williams.
+
+#pragma once
+
+#include "ruby.h"
+#include "ruby/st.h"
+
+// Per-class allocation tracking record
+struct Memory_Profiler_Capture_Allocations {
+	VALUE callback;   // Optional Ruby proc/lambda to call on allocation
+	size_t new_count;  // Total allocations seen since tracking started
+	size_t free_count; // Total frees seen since tracking started
+	// Live count = new_count - free_count
+	
+	// For detailed tracking: map object (VALUE) => state (VALUE)
+	// State is returned from callback on :newobj and passed back on :freeobj
+	st_table *object_states;
+};
+
+// Wrap an allocations record in a VALUE
+VALUE Memory_Profiler_Allocations_wrap(struct Memory_Profiler_Capture_Allocations *record);
+
+// Get allocations record from wrapper VALUE
+struct Memory_Profiler_Capture_Allocations* Memory_Profiler_Allocations_get(VALUE self);
+
+// Clear/reset allocation counts and state for a record
+void Memory_Profiler_Allocations_clear(VALUE allocations);
+
+// Initialize the Allocations class
+void Init_Memory_Profiler_Allocations(VALUE Memory_Profiler);