rspec-gc-control 1.0.0

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+### dev
+[full changelog](http://github.com/MrJoy/rspec-gc-control/compare/v1.0.0...master)
+
+Changes
+
+* Forgot to update changelog before tagging release.
+
+
+### v1.0.0
+[full changelog](http://github.com/MrJoy/rspec-gc-control/compare/1d2bd61...v1.0.0)
+
+Initial Version
+
+* Add support for controlling how often GC runs on RSpec 2.11.1.

data/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2012 Jon Frisby
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,60 @@
+# rspec-gc-control
+
+## Summary
+
+This gem extends RSpec to allow you to control how often GC cycles happen
+in order to trade increased memory usage for faster test runs.  It's an
+encapsulated and reusable version of the code shown in this article:
+
+<http://www.rubyinside.com/careful-cutting-to-get-faster-rspec-runs-with-rails-5207.html>
+
+
+## Requirements
+
+For this to work, you need a Ruby that supports explicit control over the
+garbage collector, and RSpec 2.11.1 or higher.
+
+Supported Rubies include MRI 1.9.2 and 1.9.3, and most likely Rubinius.
+
+Unsupported Rubies are:
+
+* MRI 1.8.x:  No support for `GC.count`.
+* JRuby:  `GC.enable` / `GC.disable` are no-ops.
+
+On unsupported platforms, attempting to enable explicit GC control via this
+plugin will produce a warning and have no other effect.
+
+
+## Installation and Usage
+
+Install the gem:
+
+```ruby
+gem install rspec-gc-control
+```
+
+Or if you're using bundler, add this line to your `Gemfile` and run
+`bundle install`:
+
+```ruby
+gem 'rspec-gc-control'
+```
+
+Once you have the gem installed, edit your `spec_helper.rb` file to set
+`gc_every_n_examples` to an appropriate value.  You may want to play with this
+value while watching memory consumption for the process to get a feeling for
+how significant a tradeoff you're making in terms of increased memory usage.
+
+```ruby
+RSpec.configure do |c|
+  c.gc_every_n_examples = 10
+end
+```
+
+You'll know it's working if you see output like the following at the end of
+your test run:
+
+```
+Finished in 6.45 seconds (including 7 forced GC cycle(s), totalling 0.67116 seconds)
+71 examples, 0 failures, 1 pending
+```

data/lib/rspec-gc-control.rb

@@ -0,0 +1,6 @@
+$:.unshift(File.expand_path("..", __FILE__))
+
+require 'rspec-gc-control/configuration'
+require 'rspec-gc-control/example'
+require 'rspec-gc-control/base_text_formatter'
+

data/lib/rspec-gc-control/base_text_formatter.rb

@@ -0,0 +1,31 @@
+require 'rspec/core/formatters/base_formatter'
+
+module RSpec
+  module Core
+    module Formatters
+
+      class BaseTextFormatter < BaseFormatter
+
+        # Overridden version of this method, to include output about forced GC
+        # count and duration, if explicit GC control is enabled.
+        def dump_summary(duration, example_count, failure_count, pending_count)
+          super(duration, example_count, failure_count, pending_count)
+          # Don't print out profiled info if there are failures, it just clutters the output
+          dump_profile if profile_examples? && failure_count == 0
+          output.print "\nFinished in #{format_duration(duration)}"
+
+          gc_times = examples.map { |ex| ex.execution_result[:gc_time] }.select { |t| !t.nil? && (t > 0) }
+          if(gc_times.count > 0)
+            gc_count = gc_times.count
+            gc_time = gc_times.reduce(:+)
+            output.print " (including #{gc_count} forced GC cycle(s), totalling #{format_duration(gc_time)})"
+          end
+          output.print "\n"
+          output.puts colorise_summary(summary_line(example_count, failure_count, pending_count))
+          dump_commands_to_rerun_failed_examples
+        end
+
+      end
+    end
+  end
+end

data/lib/rspec-gc-control/configuration.rb

@@ -0,0 +1,62 @@
+require 'rspec/core/configuration'
+
+module RSpec
+  module Core
+    # Extensions to RSpec::Core::Configuration to allow configuration of
+    # desired GC behavior.
+    class Configuration
+      # @private
+      define_reader :gc_every_n_examples
+
+      # @private
+      alias_method :initialize_without_gc, :initialize
+
+      # Overridden constructor to initialize `gc_every_n_examples` to 0.
+      # This disables the explicit GC control.
+      def initialize
+        initialize_without_gc
+        @gc_every_n_examples = 0
+      end
+
+      # @private
+      def gc_if_needed
+        gc_time = 0
+        if(@gc_every_n_examples > 0)
+          @test_counter = -1 if(!defined?(@test_counter))
+          @test_counter += 1
+          if(@test_counter >= (@gc_every_n_examples - 1))
+            t_before = Time.now
+            GC.enable
+            GC.start
+            GC.disable
+            gc_time = Time.now - t_before
+
+            @test_counter = 0
+          end
+        end
+        return gc_time
+      end
+
+      # If set to a value above 0, turns automatic GC off and runs it only
+      # every N tests, which can result in higher peak memory usage but lower
+      # total execution time.
+      def gc_every_n_examples=(n)
+        if(defined?(JRuby))
+          warn "Ignoring gc_every_n_examples because JRuby doesn't support GC control."
+          return
+        end
+        if(!GC.respond_to?(:count))
+          warn "Ignoring gc_every_n_examples because this Ruby implementation doesn't implement GC.count."
+          return
+        end
+        @gc_every_n_examples = n
+        if(@gc_every_n_examples > 0)
+          GC.disable
+        else
+          GC.enable
+        end
+      end
+
+    end
+  end
+end

data/lib/rspec-gc-control/example.rb

@@ -0,0 +1,26 @@
+require 'rspec/core/example'
+
+module RSpec
+  module Core
+    # Extensions to RSpec::Core::Example to perform explicit GC and capture
+    # GC execution time.
+    class Example
+    private
+
+      undef :record_finished
+      def record_finished(status, results={})
+        finished_at = Time.now
+        record results.merge(:status => status, :finished_at => finished_at, :run_time => (finished_at - (execution_result[:started_at] + (execution_result[:gc_time] || 0))))
+      end
+
+      alias_method :run_after_each_without_gc, :run_after_each
+
+      def run_after_each
+        run_after_each_without_gc
+      ensure
+        execution_result[:gc_time] = RSpec.configuration.gc_if_needed
+      end
+
+    end
+  end
+end

data/rspec-gc-control.gemspec

@@ -0,0 +1,47 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "rspec-gc-control"
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jon Frisby"]
+  s.date = "2012-08-12"
+  s.description = "Explicit control over garbage collection behavior for RSpec."
+  s.email = "jfrisby@mrjoy.com"
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.md"
+  ]
+  s.files = [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "lib/rspec-gc-control.rb",
+    "lib/rspec-gc-control/base_text_formatter.rb",
+    "lib/rspec-gc-control/configuration.rb",
+    "lib/rspec-gc-control/example.rb",
+    "rspec-gc-control.gemspec"
+  ]
+  s.homepage = "http://MrJoy.com"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.24"
+  s.summary = "Explicit control over garbage collection behavior for RSpec."
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rspec-core>, [">= 2.11.1"])
+    else
+      s.add_dependency(%q<rspec-core>, [">= 2.11.1"])
+    end
+  else
+    s.add_dependency(%q<rspec-core>, [">= 2.11.1"])
+  end
+end
+

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: rspec-gc-control
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Jon Frisby
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.11.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.11.1
+description: Explicit control over garbage collection behavior for RSpec.
+email: jfrisby@mrjoy.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.md
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/rspec-gc-control.rb
+- lib/rspec-gc-control/base_text_formatter.rb
+- lib/rspec-gc-control/configuration.rb
+- lib/rspec-gc-control/example.rb
+- rspec-gc-control.gemspec
+homepage: http://MrJoy.com
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -2268877769317612634
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Explicit control over garbage collection behavior for RSpec.
+test_files: []