hometown 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 138e3de444e2c7c0364c252e37a411f6139257d3
-  data.tar.gz: 82ae1b18916e8845d8a625501194b7eeee20d95c
+  metadata.gz: ad8a4766d74b2ef331b68288522bdcd94bb3bd2b
+  data.tar.gz: 26cd517beece08a45ce5047b0d601812133b645a
 SHA512:
-  metadata.gz: 75a8cb0ac1dcbb0bfb720845fc8cbe9c6de45dc562651229a0b4a84a595af900bec66f7e045fa66c4ca221616202549f56639131c093af23f0849b5565eaa130
-  data.tar.gz: ae6b198008255b5a3a88bf5035368249f7eaa1b2c2c929b03c9dbd305b00bdf5a4461f801c4e1565950e565ef049f1771d1f3e24cfa0136e4e508d1f633b43a0
+  metadata.gz: 6a6666c297ec7089fc96fee85f0deed49952dfa9b58d0604daf4aeffa3626b6ef11240b609df089794a210c5eb46ede866dd1c9602c3e3e45e297b02cd19b9dc
+  data.tar.gz: 8253b5cbb7f6a95423274dfad3621e2fdf9659a6d7c4af8df89ffabcfabfeaa8ae590d3cae84e18730c4a535d54517ed5a0350b56289654c3051c9db414342ef

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - 2.1.2
+  - 2.0.0
+  - 1.9.3
+  - jruby-19mode
+  - jruby-head
+  - rbx-2.2.7

data/README.md

@@ -1,9 +1,16 @@
 # Hometown
+[![Gem Version](https://badge.fury.io/rb/hometown.png)](http://badge.fury.io/rb/hometown)
+[![Build Status](https://api.travis-ci.org/jasonrclark/hometown.png)](https://travis-ci.org/jasonrclark/hometown)
+[![Code Climate](https://codeclimate.com/github/jasonrclark/hometown.png)](https://codeclimate.com/github/jasonrclark/hometown)
+[![Coverage Status](https://coveralls.io/repos/jasonrclark/hometown/badge.png?branch=master)](https://coveralls.io/r/jasonrclark/hometown)
 
 Track object creation to stamp out pesky leaks.
 
 ## Requirements
-Currently I'm testing against Ruby 2.1, but will be extending that in the future. I expect to allow back to 1.9.x, JRuby and Rubinius.
+Tests are run against MRI 1.9.3 through 2.1.2, JRuby 1.7 (latest) and head, and
+Rubinius 2.x (latest).
+
+Ruby 1.8.7 and REE are not supported. Sorry retro-Ruby fans!
 
 ## Installation
 
@@ -11,7 +18,13 @@ Currently I'm testing against Ruby 2.1, but will be extending that in the future
 
 ## Usage
 
-Find where an object was created:
+### Object Creation
+Hometown's primary use is finding where objects were instantiated.  In
+sufficiently complicated applications, this can be a real help debugging issues
+like testing side-effects (i.e. where did that thread get started from?)
+
+To find where an object was created, `Hometown.watch` its class, and then ask
+`Hometown.for` on an instance of that class to see where it started out.
 
 ```
 # examples/example.rb
@@ -32,7 +45,17 @@ $ ruby examples/example.rb
 ```
 
 
-Track disposal of an object:
+### Resource Disposal
+Though not hugely common in the Ruby world, some libraries (such as [swt]
+(https://github.com/danlucraft/swt)) require you to explicitly dispose of
+objects you create. Most often this happens when it's an interface library to
+some other system that holds OS resources until you release them back. Leaking
+is a bad idea.
+
+Hometown can help track down these leaks. To watch a class of objects to ensure
+created instances are disposed, call `Hometown.watch_for_disposal` on the
+class. `Hometown.undisposed` returns you objects indicating--with stack traces
+--all the locations where an object was created but not released.
 
 ```
 # dispose.rb
@@ -69,7 +92,7 @@ Properly disposed!
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/hometown/fork )
+1. Fork it ( https://github.com/jasonrclark/hometown/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/hometown.gemspec

@@ -18,11 +18,12 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.6"
-  spec.add_development_dependency "rake",    "~> 10.2"
-  spec.add_development_dependency "minitest","~> 5.3"
-  spec.add_development_dependency "pry",     "~> 0.9"
-  spec.add_development_dependency "pry-nav", "~> 0.2"
-  spec.add_development_dependency "guard",   "~> 2.6"
+  spec.add_development_dependency "bundler",   "~> 1.6"
+  spec.add_development_dependency "coveralls", "~> 0.7"
+  spec.add_development_dependency "rake",      "~> 10.2"
+  spec.add_development_dependency "minitest",  "~> 5.3"
+  spec.add_development_dependency "pry",       "~> 0.9"
+  spec.add_development_dependency "pry-nav",   "~> 0.2"
+  spec.add_development_dependency "guard",     "~> 2.6"
   spec.add_development_dependency "guard-minitest", "~> 1.3"
 end

data/lib/hometown.rb

@@ -1,60 +1,33 @@
-require "hometown/hooks"
+require "hometown/creation_tracer"
+require "hometown/disposal_tracer"
 require "hometown/trace"
 require "hometown/version"
-require "hometown/watch"
-require "hometown/watch_for_disposal"
 
 module Hometown
-  HOMETOWN_TRACE_ON_INSTANCE = :@__hometown_creation_backtrace
+  @creation_tracer = Hometown::CreationTracer.new
+  @disposal_tracer = Hometown::DisposalTracer.new
 
-  @undisposed      = {}
-  @watch_patches   = {}
-  @dispose_patches = {}
-
-  def self.watch(clazz)
-    return if @watch_patches.include?(clazz)
-
-    @watch_patches[clazz] = true
-    Watch.patch(clazz)
-  end
-
-  def self.watch_for_disposal(clazz, disposal_method)
-    return if @dispose_patches.include?(clazz)
-
-    watch(clazz)
-
-    @dispose_patches[clazz] = true
-    WatchForDisposal.patch(clazz, disposal_method)
+  def self.creation_tracer
+    @creation_tracer
   end
 
-  def self.already_patched?(clazz)
-    @patched.include?(clazz)
+  def self.disposal_tracer
+    @disposal_tracer
   end
 
-  def self.for(instance)
-    instance.instance_variable_get(HOMETOWN_TRACE_ON_INSTANCE)
-  end
-
-  def self.undisposed()
-    @undisposed
+  def self.watch(clazz)
+    @creation_tracer.patch(clazz)
   end
 
-  def self.create_trace(clazz, backtrace)
-    Trace.new(clazz, backtrace)
+  def self.watch_for_disposal(clazz, disposal_method)
+    @disposal_tracer.patch(clazz, disposal_method)
   end
 
-  def self.mark_for_disposal(instance)
-    trace = Hometown.for(instance)
-
-    @undisposed[trace] ||= 0
-    @undisposed[trace]  += 1
+  def self.for(instance)
+    @creation_tracer.find_trace_for(instance)
   end
 
-  def self.mark_disposed(instance)
-    trace = Hometown.for(instance)
-
-    if @undisposed[trace]
-      @undisposed[trace] -= 1
-    end
+  def self.undisposed
+    @disposal_tracer.undisposed()
   end
 end

data/lib/hometown/creation_tracer.rb

@@ -0,0 +1,67 @@
+module Hometown
+  class CreationTracer
+    def initialize
+      @tracing_classes = {}
+    end
+
+    def patch(clazz, other_instance_hook=nil)
+      if !patched?(clazz)
+        remember_patched(clazz)
+        on_creation_add_trace_for_instance(clazz)
+        install_traced_new(clazz)
+      end
+
+      # Critical that we only add other instance hooks after our primary
+      # creation hook is registered above!
+      update_on_instance_created(clazz, other_instance_hook)
+    end
+
+    def patched?(clazz)
+      @tracing_classes.include?(clazz)
+    end
+
+    def remember_patched(clazz)
+      @tracing_classes[clazz] = true
+    end
+
+    def on_creation_add_trace_for_instance(clazz)
+      update_on_instance_created(clazz, method(:add_trace_for))
+    end
+
+    def install_traced_new(clazz)
+      clazz.instance_eval do
+        class << self
+          def new_traced(*args, &blk)
+            instance = new_untraced(*args, &blk)
+            @instance_hooks.each { |hook| hook.call(instance) }
+            instance
+          end
+
+          alias_method :new_untraced, :new
+          alias_method :new, :new_traced
+        end
+      end
+    end
+
+    HOMETOWN_TRACE_ON_INSTANCE = :@__hometown_creation_backtrace
+
+    def add_trace_for(instance)
+      trace = Hometown::Trace.new(instance.class, caller[4..-1])
+      instance.instance_variable_set(HOMETOWN_TRACE_ON_INSTANCE, trace)
+    end
+
+    def find_trace_for(instance)
+      instance.instance_variable_get(HOMETOWN_TRACE_ON_INSTANCE)
+    end
+
+    # This hook allows other tracing in Hometown to get a whack at an object
+    # after it's been created without forcing them to patch new themselves
+    def update_on_instance_created(clazz, on_instance_created)
+      return unless on_instance_created
+      clazz.instance_eval do
+        @instance_hooks ||= []
+        @instance_hooks << on_instance_created
+      end
+    end
+  end
+end

data/lib/hometown/disposal_tracer.rb

@@ -0,0 +1,47 @@
+module Hometown
+  class DisposalTracer
+    attr_reader :undisposed
+
+    def initialize
+      @undisposed      = Hash.new(0)
+      @tracing_classes = {}
+    end
+
+    def patch(clazz, disposal_method)
+      return if @tracing_classes.include?(clazz)
+      @tracing_classes[clazz] = true
+
+      trace_creation(clazz)
+      patch_disposal_method(clazz, disposal_method)
+    end
+
+    def trace_creation(clazz)
+      Hometown.creation_tracer.patch(clazz, method(:mark_for_disposal))
+    end
+
+    def patch_disposal_method(clazz, disposal_method)
+      traced   = "#{disposal_method}_traced"
+      untraced = "#{disposal_method}_untraced"
+
+      clazz.class_eval do
+        define_method(traced) do |*args, &blk|
+          Hometown.disposal_tracer.notice_disposed(self)
+          self.send(untraced, *args, &blk)
+        end
+
+        alias_method untraced, disposal_method
+        alias_method disposal_method, traced
+      end
+    end
+
+    def mark_for_disposal(instance)
+      trace = Hometown.for(instance)
+      @undisposed[trace] += 1
+    end
+
+    def notice_disposed(instance)
+      trace = Hometown.for(instance)
+      @undisposed[trace] -= 1 if @undisposed[trace]
+    end
+  end
+end

data/lib/hometown/version.rb

@@ -1,3 +1,3 @@
 module Hometown
-  VERSION = "0.0.1"
+  VERSION = "0.2.0"
 end

data/test/hometown/trace_test.rb

@@ -1,4 +1,4 @@
-require 'minitest/autorun'
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "test_helper"))
 require 'hometown/trace'
 
 module Hometown

data/test/hometown_test.rb

@@ -1,4 +1,4 @@
-require 'minitest/autorun'
+require File.expand_path(File.join(File.dirname(__FILE__), "test_helper"))
 require 'hometown'
 
 class HometownTest < Minitest::Test
@@ -80,7 +80,7 @@ class HometownTest < Minitest::Test
 
     result = Hometown.undisposed
     trace = Hometown.for(traced_object)
-    assert_nil result[trace]
+    assert_equal 0, result[trace]
   end
 
   def test_marks_for_disposal

data/test/test_helper.rb

@@ -0,0 +1,7 @@
+if ENV["CI"]
+  require 'coveralls'
+  Coveralls.wear!
+end
+
+gem 'minitest'
+require 'minitest/autorun'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hometown
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Jason R. Clark
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-03 00:00:00.000000000 Z
+date: 2014-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -116,6 +130,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".travis.yml"
 - Gemfile
 - Guardfile
 - LICENSE.txt
@@ -125,13 +140,13 @@ files:
 - examples/example.rb
 - hometown.gemspec
 - lib/hometown.rb
-- lib/hometown/hooks.rb
+- lib/hometown/creation_tracer.rb
+- lib/hometown/disposal_tracer.rb
 - lib/hometown/trace.rb
 - lib/hometown/version.rb
-- lib/hometown/watch.rb
-- lib/hometown/watch_for_disposal.rb
 - test/hometown/trace_test.rb
 - test/hometown_test.rb
+- test/test_helper.rb
 homepage: http://github.com/jasonrclark/hometown
 licenses:
 - MIT
@@ -159,4 +174,5 @@ summary: Track object creation
 test_files:
 - test/hometown/trace_test.rb
 - test/hometown_test.rb
+- test/test_helper.rb
 has_rdoc: 

data/lib/hometown/hooks.rb

@@ -1,17 +0,0 @@
-module Hometown
-  class Hooks
-    def initialize
-      @hooks = []
-    end
-
-    def <<(hook)
-      @hooks << hook
-    end
-
-    def run_on(instance)
-      @hooks.each do |hook|
-        hook.call(instance)
-      end
-    end
-  end
-end

data/lib/hometown/watch.rb

@@ -1,25 +0,0 @@
-module Hometown
-  module Watch
-    def self.patch(clazz)
-      clazz.instance_eval do
-        @hooks = Hooks.new
-
-        class << self
-          def new_traced(*args, &blk)
-            trace = Hometown.create_trace(self, caller)
-
-            instance = new_original(*args, &blk)
-            instance.instance_variable_set(HOMETOWN_TRACE_ON_INSTANCE, trace)
-            instance.class.instance_variable_get(:@hooks).run_on(instance)
-
-            instance
-          end
-
-          alias_method :new_original, :new
-          alias_method :new, :new_traced
-        end
-
-      end
-    end
-  end
-end

data/lib/hometown/watch_for_disposal.rb

@@ -1,30 +0,0 @@
-module Hometown
-  module WatchForDisposal
-    def self.patch(clazz, disposal_method)
-      add_disposal_hooks(clazz)
-      patch_disposal_method(clazz, disposal_method)
-    end
-
-    def self.add_disposal_hooks(clazz)
-      hooks = clazz.instance_variable_get(:@hooks)
-      hooks << Proc.new do |instance|
-        Hometown.mark_for_disposal(instance)
-      end
-    end
-
-    def self.patch_disposal_method(clazz, disposal_method)
-      traced   = "#{disposal_method}_traced"
-      original = "#{disposal_method}_original"
-
-      clazz.class_eval do
-        define_method(traced) do |*args, &blk|
-          Hometown.mark_disposed(self)
-          self.send(original, *args, &blk)
-        end
-
-        alias_method original, disposal_method
-        alias_method disposal_method, traced
-      end
-    end
-  end
-end