memory 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bd34b6e9c3ddd2a10a3900d0507a8af35af246c5aa2ad760eb2a204731e6fbc
-  data.tar.gz: 798ec525eeba73a5e08d9f557b98727096dfde83c01aa007d83efa6f066177e9
+  metadata.gz: 266bdfec74c35392a9c086c366df9bb6ab4fb5e1b162b98d3757f690fff09ded
+  data.tar.gz: dffe8472314144b5786b5c445c6e01973114e9c3915d08aae0352fc1be76d329
 SHA512:
-  metadata.gz: b39e94db71df052b83bd85fc63aa4c37801470eb3daeaae687e5d3c208e280299bfba9dee11da71a82c2d9b34f9935d1662be1e18eb6f99043816963c2cd6591
-  data.tar.gz: 87ef4c2aae0f96a507de45f0d60b167102ba07b05e7851af80c2e306ae6e56c3a35202c766e3202485956df8a0ca4fb14b111ade24344078e09ecdcc3cfaa56e
+  metadata.gz: 4dcf3e65b4a7dee68b55919dc44004149a6febe80fde00d539d2b0361eea62dd47ab742006ef7ed75a2980829f0f58cbf1c341098ae394ac4ac3b7a4d816752b
+  data.tar.gz: '038621f8d88603eb8b0b2a89fe13e4007bc100ce0c16c53febd9d02a6cf4fa3a00c6c3e967bfa8a6aa6507e3611266cae774dc016d330fe5b22d5322beee12e3'

checksums.yaml.gz.sig

@@ -1,4 +1,2 @@
-
-5�=Iπ,�4���׼k3�Ϟ�]
-��V�K��q%o¯ڄ�?i4b�@�Y_�@���:�k�9��`ȁ2dR�x
����5�������I'(����W�Ѕ#(T��G40q�UtT³{�H���C�t�J(��hjf_�%*Q�2�4�T%�.�:#fK��
�Gi�P�Z���h���nh�ڥ�ȇwS�vƏ�;&�
-�ČTk[wr��t�k�vN���&��c}
Rn�cA�J�c�`�S��`������/x��	��H��>
+=��z�6�r��g9��j�V�,��$�$0�����SP��.��?֋�Yb
+�F�$��}����rM�|H�n���U�̮�T��q��`�i0� q��zA=b:���@)��������3�;p������-N�����6.$Zc��] �d��
�O�{@"���M���?���SWQ�-�

data/bake/memory/report.rb

@@ -5,7 +5,7 @@
 
 def initialize(...)
 	super
-
+	
 	require_relative "../../lib/memory"
 end
 
@@ -26,6 +26,6 @@ def print(input:)
 	end
 	
 	report.print($stderr)
-
+	
 	return report
 end

data/bake/memory/sampler.rb

@@ -6,7 +6,7 @@
 def initialize(...)
 	super
 	
-	require_relative '../../lib/memory'
+	require_relative "../../lib/memory"
 end
 
 # Load a sampler from one or more .mprof files.
@@ -27,7 +27,7 @@ def load(paths:)
 	paths.each do |path|
 		Console.logger.info(sampler, "Loading #{path}, #{Memory.formatted_bytes File.size(path)}")
 		
-		File.open(path, 'r', encoding: Encoding::BINARY) do |io|
+		File.open(path, "r", encoding: Encoding::BINARY) do |io|
 			unpacker = wrapper.unpacker(io)
 			count = unpacker.read_array_header
 			
@@ -56,7 +56,7 @@ end
 # @parameter output [String] Path to write the .mprof file.
 # @returns [Memory::Sampler] The input sampler.
 def dump(path, input:)
-	File.open(path, 'w', encoding: Encoding::BINARY) do |io|
+	File.open(path, "w", encoding: Encoding::BINARY) do |io|
 		input.dump(io)
 	end
 	
@@ -76,7 +76,7 @@ def load_object_space_dump(path)
 	Console.logger.info(self, "Loading heap dump from #{path} (#{Memory.formatted_bytes(file_size)})")
 	
 	sampler = nil
-	File.open(path, 'r') do |io|
+	File.open(path, "r") do |io|
 		sampler = Memory::Sampler.load_object_space_dump(io) do |line_count, object_count|
 			# Update progress based on bytes read:
 			progress.increment(io.pos - progress.current)

data/context/getting-started.md

@@ -0,0 +1,238 @@
+# Getting Started
+
+This guide explains how to get started with `memory`, a Ruby gem for profiling memory allocations in your applications.
+
+## Installation
+
+Add the gem to your project:
+
+``` bash
+$ bundle add memory
+```
+
+## Core Concepts
+
+`memory` helps you understand where your Ruby application allocates memory and which allocations are retained (not garbage collected). It has several core concepts:
+
+- A {ruby Memory::Sampler} which captures allocation data during code execution.
+- A {ruby Memory::Report} which aggregates and presents allocation statistics.
+- A {ruby Memory::Aggregate} which groups allocations by specific metrics (gem, file, class, etc.).
+
+## Usage
+
+The simplest way to profile memory allocations is using the `Memory.report` method:
+
+``` ruby
+require "memory"
+
+# Profile a block of code:
+report = Memory.report do
+	# Your code here - e.g., process 1000 user records:
+	users = []
+	1000.times do |i|
+		users << {id: i, name: "User #{i}", email: "user#{i}@example.com"}
+	end
+	
+	# Process the data:
+	users.each do |user|
+		formatted = "#{user[:name]} <#{user[:email]}>"
+	end
+end
+
+# Display the results:
+report.print
+```
+
+This will output a detailed report showing:
+
+- **Total Allocated**: All objects created during execution
+- **Total Retained**: Objects that survived garbage collection
+- **By Gem**: Memory usage grouped by gem/library
+- **By File**: Memory usage grouped by source file
+- **By Location**: Memory usage by specific file:line locations
+- **By Class**: Memory usage by object class
+- **Strings**: Special analysis of string allocations
+
+### Understanding the Output
+
+The report shows memory allocations in human-readable units (B, KiB, MiB, etc.):
+
+```
+# Retained Memory Profile
+
+- Total Allocated: (1.50 MiB in 15234 allocations)
+- Total Retained: (856.32 KiB in 8912 allocations)
+
+## By Gem (856.32 KiB in 8912 allocations)
+
+- (645.21 KiB in 6543 allocations)	my_app/lib
+- (128.45 KiB in 1234 allocations)	activerecord-7.0.8
+- (82.66 KiB in 1135 allocations)	activesupport-7.0.8
+```
+
+Each line shows:
+- The memory consumed and number of allocations in that category
+- The category name (gem, file, class, etc.)
+
+### Manual Start/Stop
+
+For more control, use the {ruby Memory::Sampler} directly:
+
+``` ruby
+require "memory"
+
+sampler = Memory::Sampler.new
+
+# Start profiling:
+sampler.start
+
+# Run your code:
+items = []
+10000.times do |i|
+	items << "Item #{i}"
+end
+
+# Stop profiling:
+sampler.stop
+
+# Generate and print the report:
+report = sampler.report
+report.print
+```
+
+This approach is useful when:
+- You need to profile specific sections of long-running code
+- You want to control exactly when profiling begins and ends
+- You're integrating with test frameworks or benchmarking tools
+
+### Filtering Allocations
+
+You can filter which allocations to track by providing a filter block to {ruby Memory::Sampler}:
+
+``` ruby
+# Only track String allocations from your application code:
+sampler = Memory::Sampler.new do |klass, file|
+	klass == String && file.include?("/lib/my_app/")
+end
+
+sampler.start
+# Your code here
+sampler.stop
+
+report = sampler.report
+report.print
+```
+
+The filter block receives:
+- `klass`: The class of the allocated object
+- `file`: The source file where the allocation occurred
+
+Return `true` to include the allocation, `false` to exclude it.
+
+### Persisting Results
+
+For analyzing large applications or comparing runs over time, you can persist allocation data to disk:
+
+``` ruby
+sampler = Memory::Sampler.new
+
+sampler.start
+# Run your code
+sampler.stop
+
+# Save the allocation data:
+File.open("profile.mprof", "w", encoding: Encoding::BINARY) do |io|
+	sampler.dump(io)
+end
+```
+
+Later, you can load and analyze the data:
+
+``` ruby
+sampler = Memory::Sampler.new
+
+# Load saved allocation data:
+data = File.read("profile.mprof", encoding: Encoding::BINARY)
+sampler.load(data)
+
+# Generate a report:
+report = sampler.report
+report.print
+```
+
+You can even combine multiple profile files:
+
+``` ruby
+sampler = Memory::Sampler.new
+
+# Load multiple profile files:
+Dir.glob("profiles/*.mprof") do |path|
+	puts "Loading #{path}..."
+	sampler.load(File.read(path, encoding: Encoding::BINARY))
+end
+
+# Generate a combined report:
+report = sampler.report
+report.print
+```
+
+This is particularly useful for:
+- **Profiling test suites**: Profile each test file separately, then combine results
+- **Production analysis**: Capture profiles from production environments and analyze offline
+- **Trend analysis**: Compare memory usage across different code versions
+
+### Custom Reports
+
+You can create custom reports with specific aggregates:
+
+``` ruby
+require "memory"
+
+# Create a custom report with only specific aggregates:
+report = Memory::Report.new([
+	Memory::Aggregate.new("By Class", &:class_name),
+	Memory::Aggregate.new("By Gem", &:gem)
+], retained_only: true)
+
+sampler = Memory::Sampler.new
+sampler.run do
+	# Your code here
+	10000.times {"test string"}
+end
+
+# Add samples to the custom report:
+report.add(sampler)
+report.print
+```
+
+The `retained_only: true` option (default) focuses on memory leaks by only showing allocations that weren't garbage collected. Set it to `false` to see all allocations:
+
+``` ruby
+# Show all allocations, not just retained ones:
+report = Memory::Report.new([
+	Memory::Aggregate.new("By Class", &:class_name)
+], retained_only: false)
+```
+
+### Exporting to JSON
+
+Reports can be exported as JSON for integration with other tools:
+
+``` ruby
+report = Memory.report do
+	# Your code
+	data = Array.new(1000) {{value: rand(1000)}}
+end
+
+# Export as JSON:
+json_output = report.to_json
+puts json_output
+
+# Or as a Ruby hash:
+hash_output = report.as_json
+```
+
+This is useful for:
+- Building custom visualization tools.
+- Integrating with CI/CD pipelines.
+- Tracking memory metrics over time in dashboards.

data/context/index.yaml

@@ -0,0 +1,12 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Memory profiling routines for Ruby 2.3+
+metadata:
+  documentation_uri: https://socketry.github.io/memory/
+  source_code_uri: https://github.com/socketry/memory.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to get started with `memory`, a Ruby gem for
+    profiling memory allocations in your applications.

data/lib/memory/report.rb

@@ -90,16 +90,16 @@ module Memory
 			}
 		end
 		
-	# Convert this report to a JSON string.
-	# @returns [String] JSON representation of this report.
-	def to_json(...)
-		as_json.to_json(...)
-	end
-
-	# Generate a human-readable representation of this report.
-	# @returns [String] Summary showing allocated and retained totals.
-	def inspect
-		"#<#{self.class}: #{@total_allocated} allocated, #{@total_retained} retained>"
+		# Convert this report to a JSON string.
+		# @returns [String] JSON representation of this report.
+		def to_json(...)
+			as_json.to_json(...)
+		end
+		
+		# Generate a human-readable representation of this report.
+		# @returns [String] Summary showing allocated and retained totals.
+		def inspect
+			"#<#{self.class}: #{@total_allocated} allocated, #{@total_retained} retained>"
+		end
 	end
 end
-end

data/lib/memory/sampler.rb

@@ -66,72 +66,72 @@ module Memory
 	# end
 	# ~~~
 	class Sampler
-	# Load allocations from an ObjectSpace heap dump.
-	#
-	# If a block is given, it will be called periodically with progress information.
-	#
-	# @parameter io [IO] The IO stream containing the heap dump JSON.
-	# @yields [line_count, object_count] Progress callback with current line and object counts.
-	# @returns [Sampler] A new sampler populated with allocations from the heap dump.
-	def self.load_object_space_dump(io, &block)
-		sampler = new
-		cache = sampler.cache
-		
-		line_count = 0
-		object_count = 0
-		report_interval = 10000
-		
-		io.each_line do |line|
-			line_count += 1
-			
-			begin
-				object = JSON.parse(line)
-			rescue JSON::ParserError
-				# Skip invalid JSON lines
-				next
-			end
-			
-			# Skip non-object entries (ROOT, SHAPE, etc.)
-			next unless object['address']
+		# Load allocations from an ObjectSpace heap dump.
+		#
+		# If a block is given, it will be called periodically with progress information.
+		#
+		# @parameter io [IO] The IO stream containing the heap dump JSON.
+		# @yields [line_count, object_count] Progress callback with current line and object counts.
+		# @returns [Sampler] A new sampler populated with allocations from the heap dump.
+		def self.load_object_space_dump(io, &block)
+			sampler = new
+			cache = sampler.cache
 			
-			# Get allocation information (may be nil if tracing wasn't enabled)
-			file = object['file'] || '(unknown)'
-			line_number = object['line'] || 0
+			line_count = 0
+			object_count = 0
+			report_interval = 10000
 			
-			# Get object type/class
-			type = object['type'] || 'unknown'
-			
-			# Get memory size
-			memsize = object['memsize'] || 0
-			
-			# Get value for strings
-			value = object['value']
-			
-			allocation = Allocation.new(
-				cache,
-				type,           # class_name
-				file,           # file
-				line_number,    # line
-				memsize,        # memsize
-				value,          # value (for strings)
-				true            # retained (all objects in heap dump are live)
-			)
+			io.each_line do |line|
+				line_count += 1
+				
+				begin
+					object = JSON.parse(line)
+				rescue JSON::ParserError
+					# Skip invalid JSON lines
+					next
+				end
+				
+				# Skip non-object entries (ROOT, SHAPE, etc.)
+				next unless object["address"]
+				
+				# Get allocation information (may be nil if tracing wasn't enabled)
+				file = object["file"] || "(unknown)"
+				line_number = object["line"] || 0
+				
+				# Get object type/class
+				type = object["type"] || "unknown"
+				
+				# Get memory size
+				memsize = object["memsize"] || 0
+				
+				# Get value for strings
+				value = object["value"]
+				
+				allocation = Allocation.new(
+					cache,
+					type,           # class_name
+					file,           # file
+					line_number,    # line
+					memsize,        # memsize
+					value,          # value (for strings)
+					true            # retained (all objects in heap dump are live)
+				)
+				
+				sampler.allocated << allocation
+				object_count += 1
+				
+				# Report progress periodically
+				if block && (object_count % report_interval == 0)
+					block.call(line_count, object_count)
+				end
+			end
 			
-			sampler.allocated << allocation
-			object_count += 1
+			# Final progress report
+			block.call(line_count, object_count) if block
 			
-			# Report progress periodically
-			if block && (object_count % report_interval == 0)
-				block.call(line_count, object_count)
-			end
+			return sampler
 		end
 		
-		# Final progress report
-		block.call(line_count, object_count) if block
-					
-		return sampler
-	end
-		
 		# Initialize a new sampler.
 		# @parameter filter [Block | Nil] Optional filter block to select which allocations to track.
 		def initialize(&filter)
@@ -231,6 +231,22 @@ module Memory
 			return report
 		end
 		
+		# Convert this sampler to a JSON-compatible summary.
+		# Returns the allocation count without iterating through all allocations.
+		# @parameter options [Hash | Nil] Optional JSON serialization options.
+		# @returns [Hash] JSON-compatible summary of sampler data.
+		def as_json(options = nil)
+			{
+				allocations: @allocated.size
+			}
+		end
+		
+		# Convert this sampler to a JSON string.
+		# @returns [String] JSON representation of this sampler summary.
+		def to_json(...)
+			as_json.to_json(...)
+		end
+		
 		# Collects object allocation and memory of ruby code inside of passed block.
 		def run(&block)
 			start

data/lib/memory/version.rb

@@ -4,8 +4,8 @@
 # Copyright, 2013-2019, by Sam Saffron.
 # Copyright, 2015-2016, by Dave Gynn.
 # Copyright, 2018, by Jonas Peschla.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 module Memory
-	VERSION = "0.6.0"
+	VERSION = "0.7.0"
 end

data/readme.md

@@ -94,6 +94,10 @@ end
 
 Please see the [project releases](https://socketry.github.io/memory/releases/index) for all releases.
 
+### v0.7.0
+
+  - Add `Memory::Sampler#as_json` and `#to_json`.
+
 ### v0.6.0
 
   - Add agent context.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.7.0
+
+  - Add `Memory::Sampler#as_json` and `#to_json`.
+
 ## v0.6.0
 
   - Add agent context.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memory
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Sam Saffron
@@ -110,6 +110,8 @@ extra_rdoc_files: []
 files:
 - bake/memory/report.rb
 - bake/memory/sampler.rb
+- context/getting-started.md
+- context/index.yaml
 - lib/memory.rb
 - lib/memory/aggregate.rb
 - lib/memory/cache.rb