memory 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 116b9be7bb4a7d1c7b906923132406708953a8e3e7d43687d82f7920192ad74f
-  data.tar.gz: bf093a25998cefbf01f8fbc79d92d23bc972c016596acb3678cd6303eb09e034
+  metadata.gz: 8ab40ebc992286597b6a01b5157fca5393b29563c7131483d2e7839f15172541
+  data.tar.gz: d5b9b73ea305840435c242a6e34bf755d94e77350846f6618467fef4fa7561ff
 SHA512:
-  metadata.gz: 403676e22f95cd9239f3da72898a9be935c100e236bd51a6fca58d2ebf472a33609efb373dff628cf5f6f1e7ed9ace28dc3abc45adbbdc9975d489539b2f853d
-  data.tar.gz: be14f62bb150ab3daec0c9743800e887e606b0ba1545725143484362278779451f9a98dab2a35126d4396d6a57e08c1ccdce28b1a21fe5e894516b16e235b79c
+  metadata.gz: 5a10c287ab778c7deb2e12b5a04e7214107ae7afbdf12e57af3423128fe0dc9c233735892ae97ec18d90f47ba46856f08ab5624389a1cb61dbdc4d9af3733bf3
+  data.tar.gz: db0d83a8c69a4bdf37e058d6a9e304a7b0608791f8a1f89ad1f2864f2d4119aa8c61c9726b813800e4b45506e1cfa2eec7227ca8eeed99170b931927878e4efb

checksums.yaml.gz.sig

@@ -1,4 +1,2 @@
-r��[�
-�g�.z]�ǝ�T�6��6�I	I[�㙢~���[u
P��f�f^t�
-��P�����@�\G�v�a��F/`���-$�h{��r 'q�o�E1$.0�Z�����i<��N�:"r��;�%_�)����1k��V�N'(�1�M{�O��/����d��\_ gI4�{
y��K�_�ŋ���a��y�?�Wb�����J
-��2>/���L�??{]������
KԔr�Rf=�~�	<X�1�Ws����':G
+5�^�R�M�(�KD��n����^�z<~�"�i�yAP����Qt��p�<D��2jlyIe�xf	���W�bS��:L�n��@
+g��A]�%��Pn�fG>b��?x�#�ն�h�	���D�&y

data/bake/memory/report.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+def initialize(...)
+	super
+
+	require_relative "../../lib/memory"
+end
+
+# Print a memory report.
+#
+# Accepts either a `Memory::Sampler` or `Memory::Report` as input.
+#
+# @parameter input [Memory::Report] The sampler or report to print.
+def print(input:)
+	# Convert Sampler to Report if needed:
+	report = case input
+	when Memory::Sampler
+		input.report
+	when Memory::Report
+		input
+	else
+		raise ArgumentError, "Expected Memory::Sampler or Memory::Report, got #{input.class}"
+	end
+	
+	report.print($stderr)
+
+	return report
+end

data/bake/memory/sampler.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+def initialize(...)
+	super
+	
+	require_relative '../../lib/memory'
+end
+
+# Load a sampler from one or more .mprof files.
+#
+# Multiple files will be combined into a single sampler, useful for
+# analyzing aggregated profiling data.
+#
+# @parameter paths [Array(String)] Paths to .mprof files.
+# @returns [Memory::Sampler] The loaded sampler with all allocations.
+def load(paths:)
+	sampler = Memory::Sampler.new
+	cache = sampler.cache
+	wrapper = sampler.wrapper
+	
+	total_size = paths.sum{|path| File.size(path)}
+	progress = Console.logger.progress(sampler, total_size)
+	
+	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|
+			unpacker = wrapper.unpacker(io)
+			count = unpacker.read_array_header
+			
+			last_pos = 0
+			
+			# Read allocations directly into the sampler's array:
+			unpacker.each do |allocation|
+				sampler.allocated << allocation
+				
+				# Update progress based on bytes read:
+				current_pos = io.pos
+				progress.increment(current_pos - last_pos)
+				last_pos = current_pos
+			end
+		end
+		
+		Console.logger.info(sampler, "Loaded #{sampler.allocated.size} allocations")
+	end
+	
+	return sampler
+end
+
+# Dump a sampler to a .mprof file.
+#
+# @parameter input [Memory::Sampler] The sampler to dump.
+# @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|
+		input.dump(io)
+	end
+	
+	Console.logger.info(self, "Saved sampler to #{path} (#{File.size(path)} bytes)")
+	
+	return input
+end
+
+# Load a sampler from an ObjectSpace heap dump.
+#
+# @parameter path [String] Path to the heap dump JSON file.
+# @returns [Memory::Sampler] A sampler populated with allocations from the heap dump.
+def load_object_space_dump(path)
+	file_size = File.size(path)
+	progress = Console.logger.progress(self, file_size)
+	
+	Console.logger.info(self, "Loading heap dump from #{path} (#{Memory.formatted_bytes(file_size)})")
+	
+	sampler = nil
+	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)
+		end
+	end
+	
+	Console.logger.info(self, "Loaded #{sampler.allocated.size} objects from heap dump")
+	
+	return sampler
+end

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

@@ -1,21 +1,24 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 module Memory
 	UNITS = {
-		0 => 'B',
-		3 => 'KiB',
-		6 => 'MiB',
-		9 => 'GiB',
-		12 => 'TiB',
-		15 => 'PiB',
-		18 => 'EiB',
-		21 => 'ZiB',
-		24 => 'YiB'
+		0 => "B",
+		3 => "KiB",
+		6 => "MiB",
+		9 => "GiB",
+		12 => "TiB",
+		15 => "PiB",
+		18 => "EiB",
+		21 => "ZiB",
+		24 => "YiB"
 	}.freeze
 	
+	# Format bytes into human-readable units.
+	# @parameter bytes [Integer] The number of bytes to format.
+	# @returns [String] Formatted string with appropriate unit (e.g., "1.50 MiB").
 	def self.formatted_bytes(bytes)
 		return "0 B" if bytes.zero?
 		
@@ -24,6 +27,8 @@ module Memory
 		"%.2f #{UNITS[scale]}" % (bytes / 10.0**scale)
 	end
 	
+	# Aggregates memory allocations by a given metric.
+	# Groups allocations and tracks totals for memory usage and allocation counts.
 	class Aggregate
 		Total = Struct.new(:memory, :count) do
 			def initialize
@@ -51,6 +56,9 @@ module Memory
 			end
 		end
 		
+		# Initialize a new aggregate with a title and metric block.
+		# @parameter title [String] The title for this aggregate.
+		# @parameter block [Block] A block that extracts the metric from an allocation.
 		def initialize(title, &block)
 			@title = title
 			@metric = block
@@ -64,6 +72,8 @@ module Memory
 		attr :total
 		attr :totals
 		
+		# Add an allocation to this aggregate.
+		# @parameter allocation [Allocation] The allocation to add.
 		def << allocation
 			metric = @metric.call(allocation)
 			total = @totals[metric]
@@ -75,10 +85,18 @@ module Memory
 			@total.count += 1
 		end
 		
+		# Sort totals by a given key.
+		# @parameter key [Symbol] The key to sort by (e.g., :memory or :count).
+		# @returns [Array] Sorted array of [metric, total] pairs.
 		def totals_by(key)
 			@totals.sort_by{|metric, total| [total[key], metric]}
 		end
 		
+		# Print this aggregate to an IO stream.
+		# @parameter io [IO] The output stream to write to.
+		# @parameter limit [Integer] Maximum number of items to display.
+		# @parameter title [String] Optional title override.
+		# @parameter level [Integer] Markdown heading level for output.
 		def print(io = $stderr, limit: 10, title: @title, level: 2)
 			io.puts "#{'#' * level} #{title} #{@total}", nil
 			
@@ -89,6 +107,9 @@ module Memory
 			io.puts nil
 		end
 		
+		# Convert this aggregate to a JSON-compatible hash.
+		# @parameter options [Hash | Nil] Optional JSON serialization options.
+		# @returns [Hash] JSON-compatible representation.
 		def as_json(options = nil)
 			{
 				title: @title,
@@ -98,7 +119,12 @@ module Memory
 		end
 	end
 	
+	# Aggregates memory allocations by value.
+	# Groups allocations by their actual values (e.g., string contents) and creates sub-aggregates.
 	class ValueAggregate
+		# Initialize a new value aggregate.
+		# @parameter title [String] The title for this aggregate.
+		# @parameter block [Block] A block that extracts the metric from an allocation.
 		def initialize(title, &block)
 			@title = title
 			@metric = block
@@ -110,6 +136,8 @@ module Memory
 		attr :metric
 		attr :aggregates
 		
+		# Add an allocation to this value aggregate.
+		# @parameter allocation [Allocation] The allocation to add.
 		def << allocation
 			if value = allocation.value
 				aggregate = @aggregates[value]
@@ -118,10 +146,17 @@ module Memory
 			end
 		end
 		
+		# Sort aggregates by a given key.
+		# @parameter key [Symbol] The key to sort by (e.g., :memory or :count).
+		# @returns [Array] Sorted array of [value, aggregate] pairs.
 		def aggregates_by(key)
 			@aggregates.sort_by{|value, aggregate| [aggregate.total[key], value]}
 		end
 		
+		# Print this value aggregate to an IO stream.
+		# @parameter io [IO] The output stream to write to.
+		# @parameter limit [Integer] Maximum number of items to display.
+		# @parameter level [Integer] Markdown heading level for output.
 		def print(io = $stderr, limit: 10, level: 2)
 			io.puts "#{'#' * level} #{@title}", nil
 			
@@ -130,6 +165,9 @@ module Memory
 			end
 		end
 		
+		# Convert this value aggregate to a JSON-compatible hash.
+		# @parameter options [Hash | Nil] Optional JSON serialization options.
+		# @returns [Hash] JSON-compatible representation.
 		def as_json(options = nil)
 			{
 				title: @title,

data/lib/memory/cache.rb

@@ -8,17 +8,23 @@
 # Copyright, 2016, by Hamdi Akoğuz.
 # Copyright, 2018, by Jonas Peschla.
 # Copyright, 2020, by Jean Boussier.
-# Copyright, 2020-2022, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 module Memory
+	# Cache for storing and looking up allocation metadata.
+	# Caches gem names, file locations, class names, and string values to reduce memory overhead during profiling.
 	class Cache
+		# Initialize a new cache with empty lookup tables.
 		def initialize
 			@gem_guess_cache = Hash.new
-			@location_cache = Hash.new { |h, k| h[k] = Hash.new.compare_by_identity }
+			@location_cache = Hash.new {|h, k| h[k] = Hash.new.compare_by_identity}
 			@class_name_cache = Hash.new.compare_by_identity
 			@string_cache = Hash.new
 		end
-
+		
+		# Guess the gem or library name from a file path.
+		# @parameter path [String] The file path to analyze.
+		# @returns [String] The guessed gem name, stdlib component, or "other".
 		def guess_gem(path)
 			@gem_guess_cache[path] ||=
 				if /(\/gems\/.*)*\/gems\/(?<gemname>[^\/]+)/ =~ path
@@ -33,15 +39,26 @@ module Memory
 					"other"
 				end
 		end
-
+		
+		# Look up and cache a file location string.
+		# @parameter file [String] The source file path.
+		# @parameter line [Integer] The line number.
+		# @returns [String] The formatted location string "file:line".
 		def lookup_location(file, line)
 			@location_cache[file][line] ||= "#{file}:#{line}"
 		end
-
+		
+		# Look up and cache a class name.
+		# @parameter klass [Class] The class object.
+		# @returns [String] The class name or `unknown` if unavailable.
 		def lookup_class_name(klass)
-			@class_name_cache[klass] ||= ((klass.is_a?(Class) && klass.name) || '<<Unknown>>').to_s
+			@class_name_cache[klass] ||= ((klass.is_a?(Class) && klass.name) || "unknown").to_s
 		end
-
+		
+		# Look up and cache a string value.
+		# Strings are truncated to 64 characters to reduce memory usage.
+		# @parameter obj [String] The string object to cache.
+		# @returns [String] A cached copy of the string (truncated to 64 characters).
 		def lookup_string(obj)
 			# This string is shortened to 200 characters which is what the string report shows
 			# The string report can still list unique strings longer than 200 characters

data/lib/memory/deque.rb

@@ -1,18 +1,23 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2022, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
-require 'objspace'
-require 'msgpack'
+require "objspace"
+require "msgpack"
 
 module Memory
+	# A double-ended queue implementation optimized for memory profiling.
+	# Stores items in segments to reduce memory reallocation overhead.
 	class Deque
+		# Initialize a new empty deque.
 		def initialize
 			@segments = []
 			@last = nil
 		end
 		
+		# Freeze this deque and all its segments.
+		# @returns [Deque] Self.
 		def freeze
 			return self if frozen?
 			
@@ -24,6 +29,9 @@ module Memory
 		
 		include Enumerable
 		
+		# Concatenate an array segment to this deque.
+		# @parameter segment [Array] The segment to append.
+		# @returns [Deque] Self.
 		def concat(segment)
 			@segments << segment
 			@last = nil
@@ -31,6 +39,9 @@ module Memory
 			return self
 		end
 		
+		# Append an item to this deque.
+		# @parameter item [Object] The item to append.
+		# @returns [Deque] Self.
 		def << item
 			unless @last
 				@last = []
@@ -42,12 +53,16 @@ module Memory
 			return self
 		end
 		
+		# Iterate over all items in the deque.
+		# @parameter block [Block] The block to yield each item to.
 		def each(&block)
 			@segments.each do |segment|
 				segment.each(&block)
 			end
 		end
 		
+		# Get the total number of items in the deque.
+		# @returns [Integer] The total number of items across all segments.
 		def size
 			@segments.sum(&:size)
 		end

data/lib/memory/report.rb

@@ -1,12 +1,17 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
-require_relative 'aggregate'
+require_relative "aggregate"
 
 module Memory
+	# A report containing aggregated memory allocation statistics.
+	# Collects and organizes allocation data by various metrics.
 	class Report
+		# Create a general-purpose report with standard aggregates.
+		# @parameter options [Hash] Options to pass to the report constructor.
+		# @returns [Report] A new report with standard aggregates.
 		def self.general(**options)
 			Report.new([
 				Aggregate.new("By Gem", &:gem),
@@ -18,6 +23,9 @@ module Memory
 			], **options)
 		end
 		
+		# Initialize a new report with the given aggregates.
+		# @parameter aggregates [Array] Array of Aggregate or ValueAggregate instances.
+		# @parameter retained_only [Boolean] Whether to only include retained allocations in aggregates.
 		def initialize(aggregates, retained_only: true)
 			@retained_only = retained_only
 			
@@ -53,6 +61,8 @@ module Memory
 			end
 		end
 		
+		# Print this report to an IO stream.
+		# @parameter io [IO] The output stream to write to.
 		def print(io = $stderr)
 			if @retained_only
 				io.puts "\# Retained Memory Profile", nil
@@ -69,6 +79,9 @@ module Memory
 			end
 		end
 		
+		# Convert this report to a JSON-compatible hash.
+		# @parameter options [Hash | Nil] Optional JSON serialization options.
+		# @returns [Hash] JSON-compatible representation.
 		def as_json(options = nil)
 			{
 				total_allocated: @total_allocated.as_json(options),
@@ -77,8 +90,16 @@ module Memory
 			}
 		end
 		
-		def to_json(...)
-			as_json.to_json(...)
-		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>"
 	end
 end
+end

data/lib/memory/rspec/profiler.rb

@@ -1,13 +1,18 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2022, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
-require_relative '../sampler'
+require_relative "../sampler"
 
 module Memory
+	# @namespace
 	module RSpec
+		# Integration with RSpec for memory profiling test suites.
+		# Profiles memory allocations for RSpec example groups and generates reports.
 		module Profiler
+			# Profile memory allocations for RSpec examples.
+			# @parameter scope [Object] The RSpec scope to apply profiling hooks to.
 			def self.profile(scope)
 				memory_sampler = nil
 				

data/lib/memory/sampler.rb

@@ -11,16 +11,21 @@
 # Copyright, 2018, by Jonas Peschla.
 # Copyright, 2018, by Espartaco Palma.
 # Copyright, 2020, by Jean Boussier.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
-require 'objspace'
-require 'msgpack'
-require 'console'
+require "objspace"
+require "msgpack"
+require "json"
+require "console"
 
-require_relative 'cache'
+require_relative "cache"
 
 module Memory
+	# MessagePack factory wrapper for serializing allocations.
+	# Registers custom types for efficient serialization of allocation data.
 	class Wrapper < MessagePack::Factory
+		# Initialize the wrapper with a cache.
+		# @parameter cache [Cache] The cache to use for allocation metadata.
 		def initialize(cache)
 			super()
 			
@@ -61,6 +66,74 @@ 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']
+			
+			# 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
+		
+		# 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)
 			@filter = filter
 			
@@ -69,6 +142,8 @@ module Memory
 			@allocated = Array.new
 		end
 		
+		# Generate a human-readable representation of this sampler.
+		# @returns [String] String showing the number of allocations tracked.
 		def inspect
 			"#<#{self.class} #{@allocated.size} allocations>"
 		end
@@ -79,6 +154,8 @@ module Memory
 		attr :wrapper
 		attr :allocated
 		
+		# Start tracking memory allocations.
+		# Disables GC and begins ObjectSpace allocation tracing.
 		def start
 			GC.disable
 			3.times{GC.start}
@@ -90,6 +167,8 @@ module Memory
 			ObjectSpace.trace_object_allocations_start
 		end
 		
+		# Stop tracking allocations and determine which ones were retained.
+		# Re-enables GC and marks retained allocations.
 		def stop
 			ObjectSpace.trace_object_allocations_stop
 			allocated = track_allocations(@generation)
@@ -116,6 +195,9 @@ module Memory
 			ObjectSpace.trace_object_allocations_clear
 		end
 		
+		# Serialize allocations to MessagePack format.
+		# @parameter io [IO | Nil] Optional IO stream to write to. If nil, returns serialized data.
+		# @returns [String | Nil] Serialized data if no IO stream provided, otherwise nil.
 		def dump(io = nil)
 			Console.logger.debug(self, "Dumping allocations: #{@allocated.size}")
 			
@@ -128,6 +210,8 @@ module Memory
 			end
 		end
 		
+		# Load allocations from MessagePack-serialized data.
+		# @parameter data [String] The serialized allocation data.
 		def load(data)
 			allocations = @wrapper.load(data)
 			
@@ -136,6 +220,9 @@ module Memory
 			@allocated.concat(allocations)
 		end
 		
+		# Generate a report from the tracked allocations.
+		# @parameter options [Hash] Options to pass to the report constructor.
+		# @returns [Report] A report containing allocation statistics.
 		def report(**options)
 			report = Report.general(**options)
 			

data/lib/memory/version.rb

@@ -7,5 +7,5 @@
 # Copyright, 2020-2024, by Samuel Williams.
 
 module Memory
-	VERSION = "0.5.0"
+	VERSION = "0.6.1"
 end

data/lib/memory.rb

@@ -5,14 +5,20 @@
 # Copyright, 2014, by Søren Skovsbøll.
 # Copyright, 2017, by Nick LaMuro.
 # Copyright, 2018, by Jonas Peschla.
-# Copyright, 2020-2022, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require_relative "memory/version"
 require_relative "memory/cache"
 require_relative "memory/report"
 require_relative "memory/sampler"
 
+# Memory profiler for Ruby applications.
+# Provides tools to track and analyze memory allocations and retention.
 module Memory
+	# Capture memory allocations from a block of code.
+	# @parameter report [Report | Nil] Optional report instance to add samples to.
+	# @parameter block [Block] The code to profile.
+	# @returns [Report] A report containing allocation statistics.
 	def self.capture(report = nil, &block)
 		sampler = Sampler.new
 		sampler.run(&block)
@@ -23,6 +29,9 @@ module Memory
 		return report
 	end
 	
+	# Generate a memory allocation report for a block of code.
+	# @parameter block [Block] The code to profile.
+	# @returns [Report] A report containing allocation statistics.
 	def self.report(&block)
 		self.capture(&block)
 	end

data/license.md

@@ -24,7 +24,7 @@ Copyright, 2019-2020, by Jean Boussier.
 Copyright, 2019, by Ashwin Maroli.  
 Copyright, 2019, by Olle Jonsson.  
 Copyright, 2019, by Danny Ben Shitrit.  
-Copyright, 2020-2024, by Samuel Williams.  
+Copyright, 2020-2025, by Samuel Williams.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -19,68 +19,47 @@ $ bundle add 'memory'
 
 ## Usage
 
-``` ruby
-require 'memory'
-
-report = Memory.report do
-	# run your code here
-end
-
-report.print
-```
-
-Or, you can use the `.start`/`.stop` methods as well:
-
-``` ruby
-require 'memory'
-
-sampler = Memory::Sampler.new
+Please see the [project documentation](https://socketry.github.io/memory/) for more details.
 
-sampler.start
-# run your code here
-sampler.stop
-
-report = sampler.report
-report.print
-```
+  - [Getting Started](https://socketry.github.io/memory/guides/getting-started/index) - This guide explains how to get started with `memory`, a Ruby gem for profiling memory allocations in your applications.
 
 ### RSpec Integration
 
 ``` ruby
 memory_sampler = nil
 config.before(:all) do |example_group|
-	name = example_group.class.description.gsub(/[^\w]+/, '-')
+	name = example_group.class.description.gsub(/[^\w]+/, "-")
 	path = "#{name}.mprof"
-
+	
 	skip if File.exist?(path)
-
+	
 	memory_sampler = Memory::Sampler.new
 	memory_sampler.start
 end
 
 config.after(:all) do |example_group|
-	name = example_group.class.description.gsub(/[^\w]+/, '-')
+	name = example_group.class.description.gsub(/[^\w]+/, "-")
 	path = "#{name}.mprof"
-
+	
 	if memory_sampler
 		memory_sampler.stop
-
+		
 		File.open(path, "w", encoding: Encoding::BINARY) do |io|
 			memory_sampler.dump(io)
 		end
-
+		
 		memory_sampler = nil
 	end
 end
 
 config.after(:suite) do
 	memory_sampler = Memory::Sampler.new
-
-	Dir.glob('*.mprof') do |path|
+	
+	Dir.glob("*.mprof") do |path|
 		$stderr.puts "Loading #{path}..."
 		memory_sampler.load(File.read(path, encoding: Encoding::BINARY))
 	end
-
+	
 	$stderr.puts "Memory usage:"
 	memory_sampler.report.print
 end
@@ -111,6 +90,14 @@ config.after(:suite) do |example|
 end
 ```
 
+## Releases
+
+Please see the [project releases](https://socketry.github.io/memory/releases/index) for all releases.
+
+### v0.6.0
+
+  - Add agent context.
+
 ## Contributing
 
 We welcome contributions to this project.
@@ -123,8 +110,8 @@ We welcome contributions to this project.
 
 ### Developer Certificate of Origin
 
-This project uses the [Developer Certificate of Origin](https://developercertificate.org/). All contributors to this project must agree to this document to have their contributions accepted.
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
 
-### Contributor Covenant
+### Community Guidelines
 
-This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,5 @@
+# Releases
+
+## v0.6.0
+
+  - Add agent context.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memory
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Sam Saffron
@@ -29,7 +29,6 @@ authors:
 - Olle Jonsson
 - Vasily Kolesnikov
 - William Tabi
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -61,7 +60,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-06-27 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bake
@@ -105,13 +104,14 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- bake/memory/profiler.rb
+- 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
@@ -122,13 +122,13 @@ files:
 - lib/memory/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/memory
 licenses:
 - MIT
 metadata:
   documentation_uri: https://socketry.github.io/memory/
   source_code_uri: https://github.com/socketry/memory.git
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -136,15 +136,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Memory profiling routines for Ruby 2.3+
 test_files: []

data/bake/memory/profiler.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2013-2018, by Sam Saffron.
-# Copyright, 2014, by Richard Schneeman.
-# Copyright, 2018, by Jonas Peschla.
-# Copyright, 2020-2022, by Samuel Williams.
-
-def check(paths:)
-	require 'console'
-	
-	total_size = paths.sum{|path| File.size(path)}
-	
-	require_relative '../../lib/memory'
-	
-	report = Memory::Report.general
-	
-	cache = Memory::Cache.new
-	wrapper = Memory::Wrapper.new(cache)
-	
-	progress = Console.logger.progress(report, total_size)
-	
-	paths.each do |path|
-		Console.logger.info(report, "Loading #{path}, #{Memory.formatted_bytes File.size(path)}")
-		
-		File.open(path) do |io|
-			unpacker = wrapper.unpacker(io)
-			count = unpacker.read_array_header
-			
-			report.concat(unpacker)
-			
-			progress.increment(io.size)
-		end
-		
-		Console.logger.info(report, "Loaded allocations, #{report.total_allocated}")
-	end
-	
-	report.print($stdout)
-end