instrumentation 0.8.0

data/CHANGELOG

@@ -0,0 +1 @@
+v0.8.0. Basic files

data/Manifest

@@ -0,0 +1,7 @@
+CHANGELOG
+lib/instrument.rb
+Manifest
+Rakefile
+README.rdoc
+test/instrument_test.rb
+test/test_helper.rb

data/README.rdoc

@@ -0,0 +1,60 @@
+= Instrument Library
+
+== Description
+
+Provides a simple API for instrumenting Ruby method invocations
+
+== Features/Problems
+
+Simply wraps methods, times invocations, and yields to the given handler.
+
+== SYNOPSIS:
+
+  class Foo
+    def go
+      sleep(rand(10) / 10)
+    end
+  end
+  
+  invocations = []
+  instrument 'Foo#go' do |obj, time, *args|
+    invocations << time
+  end
+  
+  foo = Foo.new
+  5.times { foo.go }
+  invocations.size # => 5
+  invocations.max # => the max time spent invoking Foo#go
+
+== REQUIREMENTS:
+
+* activesupport
+
+== INSTALL:
+
+* sudo gem install instrument
+
+== LICENSE:
+
+(The FiveRuns License)
+
+Copyright (c) 2008 FiveRuns Corporation
+
+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/Rakefile

@@ -0,0 +1,14 @@
+require 'rubygems'
+require 'echoe'
+
+Echoe.new 'instrumentation' do |p|
+  # Note: Update version by adding a line to CHANGELOG
+  p.author = "FiveRuns Development Team"
+  p.test_files = Dir['test/**/*_test.rb']
+  p.email  = 'dev@fiveruns.com'
+  p.project = 'fiveruns'
+  p.summary = "Provides a simple API for instrumenting Ruby method invocations."
+  p.url = "http://github.com/fiveruns/instrumentation"
+  p.dependencies = %w(activesupport)
+  p.include_rakefile = true
+end

data/instrumentation.gemspec

@@ -0,0 +1,46 @@
+
+# Gem::Specification for Instrumentation-0.8.0
+# Originally generated by Echoe
+
+Gem::Specification.new do |s|
+  s.name = %q{instrumentation}
+  s.version = "0.8.0"
+
+  s.specification_version = 2 if s.respond_to? :specification_version=
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["FiveRuns Development Team"]
+  s.date = %q{2008-05-16}
+  s.description = %q{Provides a simple API for instrumenting Ruby method invocations.}
+  s.email = %q{dev@fiveruns.com}
+  s.extra_rdoc_files = ["CHANGELOG", "lib/instrument.rb", "README.rdoc"]
+  s.files = ["CHANGELOG", "lib/instrument.rb", "Manifest", "Rakefile", "README.rdoc", "test/instrument_test.rb", "test/test_helper.rb", "instrumentation.gemspec"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/fiveruns/instrumentation}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Instrumentation", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{fiveruns}
+  s.rubygems_version = %q{1.1.1}
+  s.summary = %q{Provides a simple API for instrumenting Ruby method invocations.}
+  s.test_files = ["test/instrument_test.rb", "test/test_helper.rb"]
+
+  s.add_dependency(%q<activesupport>, [">= 0"])
+end
+
+
+# # Original Rakefile source (requires the Echoe gem):
+# 
+# require 'rubygems'
+# require 'echoe'
+# 
+# Echoe.new 'instrumentation' do |p|
+#   # Note: Update version by adding a line to CHANGELOG
+#   p.author = "FiveRuns Development Team"
+#   p.test_files = Dir['test/**/*_test.rb']
+#   p.email  = 'dev@fiveruns.com'
+#   p.project = 'fiveruns'
+#   p.summary = "Provides a simple API for instrumenting Ruby method invocations."
+#   p.url = "http://github.com/fiveruns/instrumentation"
+#   p.dependencies = %w(activesupport)
+#   p.include_rakefile = true
+# end

data/lib/instrument.rb

@@ -0,0 +1,74 @@
+require 'rubygems'
+require 'activesupport'
+
+# call-seq:
+#  instrument("ClassName#instance_method", ...) { |instance, time, *args| ... }
+#  instrument("ClassName::class_method", ...) { |klass, time, *args| ... }
+#  instrument("ClassName.class_method", ...) { |klass, time, *args| ... }
+#
+# Add a handler to be called every time a method is invoked
+def instrument(*raw_targets, &handler)
+  Instrument.add(*raw_targets, &handler)
+end
+
+module Instrument
+        
+  class Error < ::NameError; end
+
+  def self.handlers
+    @handlers ||= []
+  end
+
+  def self.add(*raw_targets, &handler)
+    raw_targets.each do |raw_target|
+      obj, meth = case raw_target
+      when /^(.+)#(.+)$/
+        [$1.constantize, $2]
+      when /^(.+)(?:\.|::)(.+)$/
+        [(class << $1.constantize; self; end), $2]
+      else
+        raise Error, "Bad target format: #{raw_target}"
+      end
+      instrument(obj, meth, &handler)
+    end
+  end  
+    
+  #######
+  private
+  #######
+
+  def self.instrument(obj, meth, &handler)
+    handlers << handler unless handlers.include?(handler)
+    offset = handlers.size - 1
+    code = wrapping meth, :instrument do |without|
+      <<-CONTENTS
+        # Invoke and time
+        _start = Time.now
+        _result = #{without}(*args, &block)
+        _time = Time.now - _start
+        # Call handler (don't change *args!)
+        ::Instrument.handlers[#{offset}].call(self, _time, *args)
+        # Return the original result
+        _result
+      CONTENTS
+    end
+    obj.module_eval code
+  rescue => e
+    raise Error, "Could not attach (#{e.message})"
+  end
+
+  def self.wrapping(meth, feature)
+    format = meth =~ /^(.*?)(\?|!|=)$/ ? "#{$1}_%s_#{feature}#{$2}" : "#{meth}_%s_#{feature}" 
+    <<-DYNAMIC
+      if instance_methods.include?("#{format % :without}")
+        # Skip instrumentation
+      else
+        def #{format % :with}(*args, &block)
+          #{yield(format % :without)}
+        end
+        alias_method_chain :#{meth}, :#{feature}
+      end
+    DYNAMIC
+  end
+      
+end

data/test/instrument_test.rb

@@ -0,0 +1,125 @@
+require File.dirname(__FILE__) << "/test_helper"
+require 'stringio'
+
+module Fake
+  class Widget
+    def turn
+    end
+  end
+  class FancyWidget < Widget
+    def screw(direction)
+      turn
+    end
+  end
+  class Cat
+    def meow
+    end
+  end
+  class Dog
+    def bark
+    end
+    def woof
+    end
+  end
+  
+  class TargetA
+  end
+
+  class TargetB
+    def exists
+    end
+  end
+
+  class TargetC
+    def exists
+    end
+  end
+
+  class TargetD
+    def exists
+    end
+  end
+  
+end
+
+
+class InstrumentFake < Test::Unit::TestCase
+
+  context "Correct Behavior" do
+  
+    setup do
+      Instrument.handlers.clear
+    end
+  
+    should "executes hooks" do
+  
+      turns = []
+    
+        instrument 'Fake::Widget#turn' do
+          turns << :turn
+        end
+        instrument 'Fake::FancyWidget#screw' do
+          turns << :screw
+        end
+  
+      widget = Fake::FancyWidget.new
+      4.times { widget.turn }
+      widget.screw(:in)
+      widget.screw(:out)
+    
+      assert_equal 8, turns.size
+      assert_equal 6, turns.select { |t| t == :turn }.size
+        
+    end
+  
+    should "works with multiple targets" do
+      calls = 0
+      instrument 'Fake::Dog#bark', 'Fake::Dog#woof' do
+        calls += 1
+      end
+      dog = Fake::Dog.new
+      dog.bark
+      dog.woof
+      assert_equal 2, calls
+      assert_equal 1, Instrument.handlers.size
+    end
+  
+  end
+
+  context "Errors" do
+  
+    setup do
+      @output = StringIO.new
+    end
+  
+    should "raise exceptions on bad targets" do
+      assert_raises NameError do
+        instrument 'Fake::BadConstant#does_not_exist' do
+        end
+      end
+      assert_raises Instrument::Error do
+        instrument 'Fake::TargetA#does_not_exist' do
+        end
+      end
+    end
+  
+    should "silently fail to reinstrument already instrumented methods" do
+      foo = 0
+      bar = 0
+      instrument 'Fake::TargetD#exists' do
+        foo += 1
+      end
+      Fake::TargetD.new.exists
+      assert_equal 1, foo
+      assert_equal 0, bar
+      instrument 'Fake::TargetD#exists' do
+        bar += 1
+      end
+      Fake::TargetD.new.exists
+      assert_equal 2, foo
+      assert_equal 0, bar
+    end
+  
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,6 @@
+require 'rubygems'
+require 'test/unit'
+require 'Shoulda'
+
+$:.unshift(File.dirname(__FILE__) << "/../lib")
+require 'instrument'

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: instrumentation
+version: !ruby/object:Gem::Version 
+  version: 0.8.0
+platform: ruby
+authors: 
+- FiveRuns Development Team
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-05-16 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Provides a simple API for instrumenting Ruby method invocations.
+email: dev@fiveruns.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- CHANGELOG
+- lib/instrument.rb
+- README.rdoc
+files: 
+- CHANGELOG
+- lib/instrument.rb
+- Manifest
+- Rakefile
+- README.rdoc
+- test/instrument_test.rb
+- test/test_helper.rb
+- instrumentation.gemspec
+has_rdoc: true
+homepage: http://github.com/fiveruns/instrumentation
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Instrumentation
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: fiveruns
+rubygems_version: 1.1.1
+signing_key: 
+specification_version: 2
+summary: Provides a simple API for instrumenting Ruby method invocations.
+test_files: 
+- test/instrument_test.rb
+- test/test_helper.rb