memtf 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aa14c68446bef3d1c846cbe75a96e1745e3be6ff
-  data.tar.gz: bc1961d37230b93cbf5f01b1f81ffe578874dab3
+  metadata.gz: f77e6fb9813978dda4987dc20dddb424c4a1c1b5
+  data.tar.gz: 6f5b28f54b82938efadaa508f09e5d550a1a2978
 SHA512:
-  metadata.gz: c08147b6310efb17f3cb25e5a57bbd58c595e6126157ab881472eaf2dc5d842a330a05ec19e2caddd76f9473cea71822d68334d0f80c8f8459ab6b85409347cb
-  data.tar.gz: f8a4922b9475ab2cfcb21a4daf21fa42a1d5d9dfc66193140c0539a1b2399333ae24d0022112586b47c26a28d05b3338d718847344a7e6c24cc88f6c303c2caf
+  metadata.gz: df1fe991d654a1c019e72121bd4c4fa38fbc8564727dc29ce0e6faa8dc2684c735e440b96758aca6bc50dd462fdeb3176aa8513978e14ffc73ce6a94d69af660
+  data.tar.gz: 9abcd938d071c1728be1e6609f89747492d80df7b9087d510e50266a9b5a304b2aab4e418e8f0c438d0e666269fbf949d9fd2bf767223ae96280a4ee5fbe110b

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 2.1.0-preview2
+  - 2.0.0
+  - 1.9.3

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+Unreleased ([changes](https://github.com/dresselm/memtf/compare/v0.0.2...master))
+====================
+
+v0.0.2
+=====================
+* Changed 'Memtf.finish' to 'Memtf.stop'
+* Added support for a row in the report that consolidates the memory heap sizes of
+  all classes that do not meet the threshold.  This is labeled as 'Others*'.
+* Updated documentation and specs
+* Hooked into Travis
+* Added development support for guard-rspec

data/Guardfile

@@ -0,0 +1,5 @@
+guard :rspec do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/README.md

@@ -1,7 +1,11 @@
+[![Build Status](https://secure.travis-ci.org/dresselm/memtf.png)](http://travis-ci.org/dresselm/memtf)
+
 # Memtf
 
 A simple utility to help isolate memory leaks in your ruby applications.
 
+## Why do we need another 'memory profiler'?
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -16,25 +20,32 @@ Or install it yourself as:
 
     $ gem install memtf
 
+## Prerequisites
+
+The APIs used by the gem require ruby 1.9.3+.
+
 ## Usage
-    
+
     $ bundle exec irb
+
     > require 'memtf'
+
     > Memtf.start
     > # ... do some stuff ...
-    > Memtf.finish 
+    > Memtf.stop
+
     > # or, wrap around a block
     > Memtf.around { ... }
 
 ## Example
-    
+
     > require 'memtf'
-    > 
+    >
     > leaky_array = []
     > Memtf.around do
 	>   500000.times { |i| leaky_array << "#{i % 2}-#{Time.now.to_i}" }
     > end
- 
+
     +-----------------------------+---------+---------+--------+
     | Class                       | Objects | Leakage | Impact |
     +-----------------------------+---------+---------+--------+
@@ -48,6 +59,7 @@ Or install it yourself as:
     | Thread                      | 0       | 0.000MB | 0.00%  |
     +-----------------------------+---------+---------+--------+
 
+## What should I do with these results?
 
 ## Contributing
 

data/Rakefile

@@ -1 +1,6 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/memtf/analyzer.rb

@@ -1,35 +1,44 @@
 require 'objspace'
 
 class Memtf::Analyzer
+
+  attr_reader :threshold, :filter
+
+  DEFAULT_THRESHOLD = 0.005
   MB = 1024.0**2
 
+  # @param [Hash] options
   def self.analyze(options={})
     new(options).analyze
   end
 
+  # @param [String] group
+  # @return [Hash]
   def self.analyze_group(group)
-    start_analysis = Memtf::Persistance.load(Memtf::START_STAGE, group)
-    end_analysis   = Memtf::Persistance.load(Memtf::FINISH_STAGE, group)
+    start_analysis = Memtf::Persistance.load(Memtf::START,  group)
+    end_analysis   = Memtf::Persistance.load(Memtf::STOP,   group)
 
-    comparison = {}
+    comparison    = {}
     total_memsize = 0
 
     end_analysis.each do |clazz,end_stats|
-      start_stats = start_analysis[clazz]
+      start_stats       = start_analysis[clazz]
       comparison[clazz] = {}
 
       end_stats.each do |stat_key, stat_values|
         start_val = start_stats.nil? ? 0 : start_stats[stat_key]
-        end_val = end_stats[stat_key]
-        delta   = end_val - start_val
-        total_memsize += delta if stat_key == 'size'
+        end_val   = end_stats[stat_key]
+        delta     = end_val - start_val
         comparison[clazz][stat_key] = delta
+
+        # Perhaps just compare this
+        total_memsize += delta if stat_key == 'size'
       end
     end
 
-    # Determine relative impact of each class
+    # Determine the relative memory impact of each class
     comparison.keys.each do |klazz|
-      stats = comparison[klazz]
+      stats           = comparison[klazz]
       stats['impact'] = stats['size'] / total_memsize
     end
 
@@ -37,40 +46,92 @@ class Memtf::Analyzer
   end
 
   def initialize(options={})
-    @class_or_module_filter = options[:class_or_module_filter]
-    @threshold = options.fetch(:threshold, 0.005)
+    @filter    = options[:filter]
+    @threshold = options.fetch(:threshold, DEFAULT_THRESHOLD)
   end
 
+  # @return [Hash]
   def analyze
     GC.start
 
-    class_stats   = {}
+    classes_stats = {}
     total_memsize = 0
 
-    obj_space_routine = lambda do |obj|
+    # Track the memory footprint of each class
+    # and calculate the cumulative footprint.
+    #
+    # Output:
+    #
+    #   {
+    #     'Hash'   => [10, 15],
+    #     'Fixnum' => [1],
+    #     'Array'  => [20, 30, 40],
+    #     'String' => [2,1]
+    #   }
+    #
+    ObjectSpace.each_object do |obj|
       if (clazz = obj.class).respond_to?(:name)
-        class_name = clazz.name
-        class_stat = (class_stats[class_name] ||= [])
-        obj_memsize = ObjectSpace.memsize_of(obj)
-        class_stat << obj_memsize
+        class_name    = clazz.name
+        class_stats   = (classes_stats[class_name] ||= [])
+
+        obj_memsize   = ObjectSpace.memsize_of(obj)
+        class_stats   << obj_memsize
         total_memsize += obj_memsize
       end
     end
 
-    if @class_or_module_filter.nil?
-      ObjectSpace.each_object(&obj_space_routine)
-    else
-      ObjectSpace.each_object(@class_or_module_filter,&obj_space_routine)
-    end
+    sorted_mem_hogs = identify_hogs(classes_stats, total_memsize)
+    translate_hogs(sorted_mem_hogs)
+  end
 
-    threshold = @threshold * total_memsize
-    mem_hogs = class_stats.select do |k,v|
-      v.sum >= threshold
+  private
+
+  # Identify the most meaningful memory hogs, rollup the non-meaningful
+  # classes into a single slot called 'Other*' and sort the results.
+  #
+  # Output:
+  #
+  #   {
+  #     'Array'   => [20, 30, 40],
+  #     'Hash'    => [10, 15],
+  #     'Others*' => [1,2,1]
+  #   }
+  #
+  # TODO Ensure threshold is easily configurable
+  #
+  # @param [Hash] memory_by_class
+  # @param [Fixnum] total_memory_size
+  # @return [Hash]
+  def identify_hogs(memory_by_class, total_memory_size)
+    mem_threshold = threshold * total_memory_size
+    mem_hogs, others = {}, []
+    memory_by_class.each_pair do |k,v|
+      if v.sum >= mem_threshold
+        mem_hogs[k] = v
+      else
+        others += v
+      end
     end
-    sorted_mem_hogs = Hash[mem_hogs.sort_by {|k,v| -v.sum }]
 
+    mem_hogs.merge!({'Others*' => others})
+    Hash[mem_hogs.sort_by {|k,v| -v.sum }]
+  end
+
+  # Translate hogs into a suitable format
+  #
+  # Output:
+  #
+  #   {
+  #     'Array'   => {:count => 3, :size => 90},
+  #     'Hash'    => {:count => 2, :size => 25},
+  #     'Others*' => {:count => 3, :size => 4}
+  #   }
+  #
+  # @param [Hash] memory_hogs
+  # @return [Hash]
+  def translate_hogs(memory_hogs)
     smh_hash = {}
-    sorted_mem_hogs.each do |k,v|
+    memory_hogs.each do |k,v|
       count = v.size
       size  = v.sum / MB
 
@@ -78,8 +139,8 @@ class Memtf::Analyzer
         count: count,
         size: size
       }
-    end; nil
-
+    end
     smh_hash
   end
+
 end

data/lib/memtf/persistance.rb

@@ -5,6 +5,9 @@ class Memtf::Persistance
   OUTPUT_DIR = "tmp/memtf"
 
   class << self
+    # @param [String] name
+    # @param [String] group
+    # @param [Object] payload
     def save(name, group, payload)
       group_directory = group_dir(group)
       FileUtils.mkdir_p("#{group_directory}")
@@ -15,6 +18,9 @@ class Memtf::Persistance
       end
     end
 
+    # @param [String] name
+    # @param [String] group
+    # @return [Object]
     def load(name, group)
       load_file = "#{group_dir(group)}/#{name}.json"
       ::MultiJson.decode File.read(load_file)
@@ -22,6 +28,8 @@ class Memtf::Persistance
 
     private
 
+    # @param [String] group
+    # @return [String] the group dir
     def group_dir(group)
       "#{OUTPUT_DIR}/#{group}"
     end

data/lib/memtf/reporter.rb

@@ -4,31 +4,34 @@ class Memtf::Reporter
 
   attr_reader :group, :options
 
+  # @param [String] group
   def self.report(group)
     new(group).report
   end
 
   def initialize(group, options={})
-    @group = group
+    @group   = group
     @options = options
   end
 
+  # @return [Terminal::Table]
   def report
-    table = Terminal::Table.new(:headings => ['Class', 'Objects', 'Leakage', 'Impact']) do |t|
+    Terminal::Table.new(:headings => ['Class', 'Objects', 'Leakage', 'Impact']) do |t|
       group_analysis = Memtf::Analyzer.analyze_group(group)
       group_analysis.sort_by { |k,v| -v['impact'] }.each do |k,v|
         t << [k,v['count'],to_MB(v['size']),to_pct(v['impact'])]
       end
     end
-    puts table
   end
 
   private
 
+  # @param [Number] bytes
   def to_MB(bytes)
     "%.3fMB" % [bytes]
   end
 
+  # @param [Number] num
   def to_pct(num)
     "%.2f%" % [num * 100]
   end

data/lib/memtf/runner.rb

@@ -1,21 +1,27 @@
 class Memtf::Runner
-	attr_reader :group, :options
+	attr_reader :group, :options, :report
 
+  # @param [String] stage
+  # @param [Hash] options
 	def self.run(stage, options={})
 		new(options).run(stage)
 	end
 
 	def initialize(options={})
-		@group = options.delete(:group) || Time.now.to_i
+		@group   = options.delete(:group) || Time.now.to_i
 		@options = options
 	end
 
+  # @param [String] stage
 	def run(stage)
 		analysis = Memtf::Analyzer.analyze(options)
     Memtf::Persistance.save(stage, group, analysis)
     analysis = nil
 
-    Memtf::Reporter.report(group) if stage == Memtf::FINISH_STAGE
+    if stage == Memtf::STOP
+      @report = Memtf::Reporter.report(group)
+      puts @report
+    end
 
 		self
 	end

data/lib/memtf/utilities/array.rb

@@ -1,5 +1,6 @@
 module Memtf::Utilities::Array
-	def sum
+  # @return [Number]
+  def sum
 		inject(0) { |sum, elem| sum + elem }
 	end
 end

data/lib/memtf/version.rb

@@ -1,3 +1,3 @@
 module Memtf
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/memtf.rb

@@ -1,24 +1,31 @@
 module Memtf
-  START_STAGE = :start
-  FINISH_STAGE = :finish
+  # Represents the starting
+  START = :start
+  # Represents the end of a run
+  STOP  = :stop
 
   class << self
     attr_accessor :runner
 
+    # @param [Hash] options
+    # @return [Runner]
     def start(options={})
-      self.runner = Runner.run(START_STAGE, options)
+      self.runner = Runner.run(START, options)
     end
 
-    def finish(options={})
-      Runner.run(FINISH_STAGE, options.merge(:group => self.runner.group))
+    # @param [Hash] options
+    def stop(options={})
+      default_group = self.runner.group
+      Runner.run(STOP, {:group => default_group}.merge(options))
     ensure
       self.runner = nil
     end
 
+    # @param [Hash] options
     def around(options={}, &block)
       start(options)
       block.call if block_given?
-      finish(options)
+      stop(options)
     end
   end
 end

data/memtf.gemspec

@@ -25,5 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "pry"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec"
+  spec.add_development_dependency "guard-rspec"
   spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "yard"
 end

data/spec/integration/memtf_spec.rb

@@ -0,0 +1,58 @@
+require 'spec_helper'
+
+describe 'Integration tests' do
+  class Leak < Struct.new(:id, :name); end
+  class LeakyHarness < Struct.new(:leaker)
+    def leak
+      25000.times do |index|
+        leaker << Leak.new(index, "Name: #{index}")
+      end
+    end
+  end
+
+  # This is janky, but works for now as a simplistic check.
+  # Since we are at the mercy of the GC, these specs are
+  # generally going to lack any consistent output.
+  def leaker_class_names(runner)
+    report = runner.report
+    rows   = report.rows
+    rows.map { |row| row.cells.first.value }
+  end
+
+  it 'should expose the memory leak' do
+    arr     = []
+    harness = LeakyHarness.new(arr)
+    runner  = Memtf.around do
+      harness.leak
+    end
+
+    leaker_class_names(runner).should include('Array')
+  end
+
+  it 'should rollup minor leaks into Other*' do
+    arr     = []
+    harness = LeakyHarness.new(arr)
+    runner  = Memtf.around do
+      harness.leak
+    end
+
+    leaker_class_names(runner).should include('Others*')
+  end
+
+  context 'when the memory leak is fixed' do
+    it 'should not expose a memory leak' do
+      runner = Memtf.around do
+        arr     = []
+        harness = LeakyHarness.new(arr)
+        harness.leak
+
+        harness.leaker.each { |leak| leak = nil}
+        harness.leaker = nil
+        harness        = nil
+        arr            = nil
+      end
+
+      leaker_class_names(runner).should_not include('Array')
+    end
+  end
+end

data/spec/lib/memtf_spec.rb

@@ -0,0 +1,61 @@
+require 'spec_helper'
+
+describe Memtf do
+  let(:options) { {} }
+
+  describe '.start' do
+    it 'should delegate to Memtf::Runner' do
+      Memtf::Runner.should_receive(:run).with(Memtf::START, options)
+
+      Memtf.start(options)
+    end
+
+    it 'should set the runner variable' do
+      Memtf.runner.should be_nil
+
+      expected_runner = Memtf.start(options)
+
+      Memtf.runner.should_not be_nil
+      Memtf.runner.should == expected_runner
+    end
+  end
+
+  describe '.stop' do
+    it 'should delegate to Memtf::Runner' do
+      Memtf::Runner.should_receive(:run).with(Memtf::STOP, hash_including(:group))
+
+      Memtf.stop(options)
+    end
+
+    it 'should clear the runner variable' do
+      runner = Memtf.start(options)
+      Memtf.runner.should_not be_nil
+
+      Memtf.stop(options)
+      Memtf.runner.should be_nil
+    end
+  end
+
+  describe '.around' do
+    it 'should delegate to start' do
+      Memtf.should_receive(:start).with(options)
+      Memtf.stub(:stop)
+
+      Memtf.around(options) { a = 1 + 2 }
+    end
+
+    it 'should delegate to finish' do
+      Memtf.should_receive(:stop).with(options)
+
+      Memtf.around(options) { a = 1 + 2 }
+    end
+
+    it 'should call the given block' do
+      Memtf.stub(:stop)
+      lambda = lambda { a = 1 + 2 }
+      lambda.should_receive(:call)
+
+      Memtf.around(options,&lambda)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'simplecov'
+require 'memtf'

metadata

@@ -1,111 +1,139 @@
 --- !ruby/object:Gem::Specification
 name: memtf
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Matthew Dressel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-22 00:00:00.000000000 Z
+date: 2013-12-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: terminal-table
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: A simple utility to help you isolate the little bastards that are stealing
@@ -116,10 +144,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .ruby-gemset
-- .ruby-version
+- ".gitignore"
+- ".ruby-gemset"
+- ".ruby-version"
+- ".travis.yml"
+- CHANGELOG.md
 - Gemfile
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -132,6 +163,9 @@ files:
 - lib/memtf/utilities/array.rb
 - lib/memtf/version.rb
 - memtf.gemspec
+- spec/integration/memtf_spec.rb
+- spec/lib/memtf_spec.rb
+- spec/spec_helper.rb
 homepage: http://github.com/dresselm/memtf
 licenses:
 - MIT
@@ -142,18 +176,22 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 2.2.0
 signing_key: 
 specification_version: 4
 summary: Leaking memory like a sieve? Cursing? Memtf is here to help.
-test_files: []
+test_files:
+- spec/integration/memtf_spec.rb
+- spec/lib/memtf_spec.rb
+- spec/spec_helper.rb
+has_rdoc: