memory 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bd34b6e9c3ddd2a10a3900d0507a8af35af246c5aa2ad760eb2a204731e6fbc
-  data.tar.gz: 798ec525eeba73a5e08d9f557b98727096dfde83c01aa007d83efa6f066177e9
+  metadata.gz: 8ab40ebc992286597b6a01b5157fca5393b29563c7131483d2e7839f15172541
+  data.tar.gz: d5b9b73ea305840435c242a6e34bf755d94e77350846f6618467fef4fa7561ff
 SHA512:
-  metadata.gz: b39e94db71df052b83bd85fc63aa4c37801470eb3daeaae687e5d3c208e280299bfba9dee11da71a82c2d9b34f9935d1662be1e18eb6f99043816963c2cd6591
-  data.tar.gz: 87ef4c2aae0f96a507de45f0d60b167102ba07b05e7851af80c2e306ae6e56c3a35202c766e3202485956df8a0ca4fb14b111ade24344078e09ecdcc3cfaa56e
+  metadata.gz: 5a10c287ab778c7deb2e12b5a04e7214107ae7afbdf12e57af3423128fe0dc9c233735892ae97ec18d90f47ba46856f08ab5624389a1cb61dbdc4d9af3733bf3
+  data.tar.gz: db0d83a8c69a4bdf37e058d6a9e304a7b0608791f8a1f89ad1f2864f2d4119aa8c61c9726b813800e4b45506e1cfa2eec7227ca8eeed99170b931927878e4efb

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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memory
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 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