frequent 0.1

data/.gitignore

@@ -0,0 +1,4 @@
+Gemfile.lock
+.bundle
+vendor
+

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in tape_deck.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2012 Ben Weintraub
+
+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,153 @@
+# Frequent
+
+Frequent is a little Ruby metaprogramming demo gem that can keep track of what's
+happening during your Ruby program's execution - specifically, how many times a
+targeted method is called.
+
+## Usage
+
+To use frequent, install the gem, then `require 'frequent'` in one of your source
+files and set the `COUNT_CALLS_TO` environment variable to the name of the
+method you'd like to count calls to. Like this:
+
+```
+require 'frequent'
+
+100.times do
+  puts "hello, frequent".split(',').inspect
+end
+```
+
+```
+$ COUNT_CALLS_TO='String#split' ruby test.rb
+...
+String#split called 100 times
+```
+
+Following Ruby conventions, instance methods are identified with a hash
+(e.g. `String#split`), and class methods are identified with a period
+(e.g. `File.join`).
+
+### API
+
+You can also use the `Frequent` module to manually place probes in your code:
+
+```
+probe = Frequent.instrument('MyClass#instance_method')
+...
+probe.calls # number of calls to target since instrumentation
+```
+
+If you're only interested in capturing calls during a specific part of your
+code's execution, you can pass a block to `instrument`, during which
+instrumentation will be enabled:
+
+```
+probe = Frequent.instrument('MyClass.method') do
+  ...
+end
+probe.calls # number of calls to target that happened in the block
+```
+
+Your targetd class/module and method need not be defined yet at the time of
+instrumentation, but see the performance section below for notes about the
+performance implementations of instrumenting not-yet-defined targets.
+
+## Internals
+
+Frequent works by overwriting the original implementation of the targeted method
+with an instrumented version that keeps a call count, using Ruby's `class_eval`,
+`alias_method`, and `define_method` facilities. The original version of the
+instrumented method is saved so that it can be optionally restored after
+instrumentation.
+
+## Performance
+
+Frequent is relatively low-overhead, but there are a few things to keep in mind
+regarding performance:
+
+1. You'll get better performance if you place your probes *after* your target
+   method has been defined. Frequent will attempt to place your probe immediately
+   upon calls to `Frequent.instrument`, but if it ever encounters a probe that it
+   cannot place yet due to a missing host class/module or method, it will make
+   use of the `method_added`, `singleton_method_added`, and `included` hooks in
+   Ruby.
+
+   These hooks will cause a bit of code to execute each time a new method is
+   added to a Ruby module in your process, and each time a module is included
+   in a new class. Frequent uses these hooks so that it has a chance to place
+   instrumentation as soon as your targeted class/module and method become
+   available.
+
+   Most Ruby processes don't add many additional methods or create additional
+   classes after an initial start-up sequence, meaning that the performance
+   impact of using these hooks should be generally limited to a slightly higher
+   fixed start-up cost for your process.
+
+2. Calls to instrumented methods will be slower than calls to uninstrumented
+   methods. Only methods that are actually instrumented will be subject to this
+   added overhead.
+
+   The degree to which this affects your program's performance in practice will
+   depend heavily on how hot your instrumented method is.
+   Instrumentation of a method called in a tight loop many times during your
+   program's execution will be more expensive overall than instrumentation of a
+   method only called a few times during the life of your program.
+
+The benchmark in `spec/frequent_spec.rb` (run with `bundle exec rake test BENCH=1`)
+attempts to measure the overhead incurred by instrumentation of a method with
+Frequent. The benchmark compares times to call empty instrumented and
+uninstrumented methods (both class and instance methods).
+
+When interpreting the results, keep in mind that most methods worth
+instrumenting are not empty -- that is, they do some non-trivial work that will
+help amortize the per-call overhead.
+
+Benchmark results will vary from machine to machine (and between different Ruby
+implementations), but on the author's machine, the overhead introduced by 
+instrumenting a method is ~0.5 μs / call. This represents a slowdown of about
+2.5x - 7x for a completely empty method call (depending on whether a class or
+instance method is being instrumented).
+
+## Caveats
+
+### method_missing
+
+In Ruby, it's fairly common to encounter methods that aren't explicitly defined,
+but are instead dynamically implemented using Ruby's `method_missing` facility.
+Frequent will not work for methods defined in this way.
+
+The main challenge in dealing with methods defined through `method_missing` is
+knowing when to place instrumentation. In order for instrumentation of
+`method_missing` methods to work, probes must be placed immediately upon
+creation of the targeted class or module - `method_added` is of no use here,
+since the target method is never actually added.
+
+There's unfortunately no `const_added` hook available in Ruby (though there was
+discussion on the mailing list of adding one a while ago), and the author has
+not found any alternatives for detecting module / class creation that he finds
+sufficiently robust, simple, and performant.
+
+Alternatives include using `set_trace_func` temporarily until the target class
+or method has been created and then disabling it (slow and complex) and looking
+for placeable probes after each `require` or `load` (doesn't work for 
+dynamically-created classes).
+
+### Metaprogramming
+
+Frequent isn't magic - it relies on the same hooks and facilities that are made
+available by the Ruby interpreter to any code in your program. That means it's
+probably possible to break or trick it in many ways.
+
+### Instrumenting the same target multiple times
+
+This won't work, and should probably raise an exception, but currently just
+fails.
+
+## License
+
+MIT license. See LICENSE for details.
+
+## Author
+
+Ben Weintraub - benweint@gmail.com

data/Rakefile

@@ -0,0 +1,9 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'spec'
+  test.pattern = 'spec/**/*_spec.rb'
+  test.verbose = true
+end

data/frequent.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Ben Weintraub"]
+  gem.email         = ["benweint@gmail.com"]
+  gem.description   = %q{Ruby method instrumentation demo}
+  gem.summary       = %q{Ruby method instrumentation demo}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.test_files    = gem.files.grep(%r{^(spec)/})
+  gem.name          = "frequent"
+  gem.require_paths = ["lib"]
+  gem.version       = '0.1'
+
+  gem.add_development_dependency('rake')
+  gem.add_development_dependency('minitest')
+  gem.add_development_dependency('minitest-matchers')
+end

data/lib/frequent.rb

@@ -0,0 +1,147 @@
+module Frequent
+  VERSION = 0.1
+
+  ProbeNameError = Class.new(StandardError)
+
+  def self.instrument(name)
+    probe = Frequent::Probe.new(name)
+    probes[name] = probe
+    Frequent::Deferred.enable! unless probe.enabled?
+    if block_given?
+      yield
+      probe.disable!
+      probes.delete(name)
+    end
+    probe
+  end
+
+  def self.constantize(name)
+    names = name.split('::')
+    names.shift if names.first == ''
+    constant = Object
+    until names.empty?
+      n = names.shift
+      return nil unless constant.const_defined?(n)
+      constant = constant.const_get(n, false)
+    end
+    constant
+  end
+
+  def self.probes
+    @probes ||= {}
+  end
+end
+
+module Frequent
+  class Probe
+    attr_reader :name, :calls, :class_name, :method_name, :original_implementation
+    alias_method :to_s, :name
+
+    def initialize(name)
+      @calls = 0
+      @name = name
+      @enabled = false
+      parse_name(name)
+      enable! if ready?
+    end
+
+    def increment
+      @calls += 1
+    end
+
+    def enabled?
+      @enabled
+    end
+
+    def ready?
+      !enabled? && target_defined?
+    end
+
+    def method_owner
+      owner = Frequent.constantize(class_name)
+      return unless owner
+      @type == :instance ? owner : owner.singleton_class
+    end
+
+    def target_defined?
+      owner = method_owner
+      owner && (
+        owner.method_defined?(method_name) ||
+        owner.private_instance_methods.include?(method_name)
+      )
+    end
+
+    def enable!
+      unless @enabling
+        @enabling = true
+        @original_implementation = method_owner.instance_method(method_name)
+        probe = self
+        aliased_name = self.aliased_name
+        method_owner.class_eval do
+          alias_method aliased_name, probe.method_name
+          define_method(probe.method_name) do |*args, &blk|
+            probe.increment
+            send(aliased_name, *args, &blk)
+          end
+        end
+        @enabled = true
+        @enabling = false
+      end
+    end
+
+    def disable!
+      if enabled?
+        probe = self
+        method_owner.class_eval do
+          define_method(probe.method_name, probe.original_implementation)
+          remove_method(probe.aliased_name)
+        end
+      end
+    end
+
+    def aliased_name
+      "__frequent_original_#{method_name}".to_sym
+    end
+
+    def parse_name(name)
+      md = name.match(/(.*)(\.|\#)(.*)/)
+      raise ProbeNameError.new("Failed to parse probe name '#{name}'") unless md
+      class_name, sep, method_name = md[1..3]
+      @class_name = class_name
+      @type = (sep == '#') ? :instance : :class
+      @method_name = method_name.to_sym
+    end
+  end
+end
+
+module Frequent
+  module Deferred
+    def self.place_by_name(name)
+      p = Frequent.probes[name]
+      p.enable! if p && p.ready?
+    end
+
+    def self.enable!
+      return if @enabled
+      ::Module.class_eval do
+        def method_added(m)
+          Frequent::Deferred.place_by_name("#{self}##{m}")
+        end
+
+        def singleton_method_added(m)
+          Frequent::Deferred.place_by_name("#{self}.#{m}")
+        end
+
+        def included(host)
+          Frequent.probes.values.select(&:ready?).each(&:enable!)
+        end
+      end
+      @enabled = true
+    end
+  end
+end
+
+if ENV['COUNT_CALLS_TO']
+  probe = Frequent.instrument(ENV['COUNT_CALLS_TO'])
+  at_exit { puts "#{probe} called #{probe.calls} times" }
+end

data/spec/frequent_spec.rb

@@ -0,0 +1,221 @@
+require 'spec_helper'
+
+describe Frequent do
+  before :each do
+    class Potato
+      def instance_method; end
+      def block_method(x); yield x; end
+      def self.class_method(*args); end
+
+      def self.recursive_class_method(n)
+        return if n == 1
+        recursive_class_method(n-1)
+      end
+
+      def self.respond_to?(method)
+        method.to_s == 'class_missing_method' ? true : super
+      end
+
+      def overridden_method; end
+
+      protected
+      def protected_instance_method; end
+
+      private
+      def private_instance_method; end
+    end
+
+    class RedPotato < Potato
+      def overridden_method; end
+    end
+  end
+
+  describe 'probe name parsing' do
+    it 'should raise ProbeNameError on invalid probe name' do
+      proc { Frequent.instrument("Lava$monster") }.must_raise(Frequent::ProbeNameError)
+    end
+  end
+
+  describe 'instance method instrumentation' do
+    it 'should support simple method call counting' do
+      p = Frequent.instrument('Potato#instance_method')
+      11.times { Potato.new.instance_method }
+      p.calls.must_equal(11)
+    end
+
+    it 'should apply to already-created instances' do
+      instance = Potato.new
+      p = Frequent.instrument('Potato#instance_method')
+      3.times { instance.instance_method }
+      p.calls.must_equal(3)
+    end
+
+    it 'should not count calls identically-named methods from parent class' do
+      p0 = Frequent.instrument('Potato#overridden_method')
+      p1 = Frequent.instrument('RedPotato#overridden_method')
+      2.times { Potato.new.overridden_method }
+      3.times { RedPotato.new.overridden_method }
+      p0.calls.must_equal(2)
+      p1.calls.must_equal(3)
+    end
+
+    it 'should support private / protected methods' do
+      p0 = Frequent.instrument('Potato#private_instance_method')
+      p1 = Frequent.instrument('Potato#protected_instance_method')
+      3.times { Potato.new.send(:private_instance_method) }
+      4.times { Potato.new.send(:protected_instance_method) }
+      p0.calls.must_equal(3)
+      p1.calls.must_equal(4)
+    end
+
+    it 'should support instrumenting methods on Object' do
+      p = Frequent.instrument('Object#tainted?') do
+        Object.new.tainted?
+      end
+      p.calls.must_equal(1)
+    end
+
+    it 'should pass-thru blocks and args' do
+      v = nil
+      p = Frequent.instrument('Potato#block_method')
+      Potato.new.block_method(42) { |n| v = n }
+      v.must_equal(42)
+      p.calls.must_equal(1)
+    end
+  end
+
+  describe 'instrumentation of class methods' do
+    it 'should support simple call counting' do
+      p = Frequent.instrument('Potato.class_method')
+      9.times { Potato.class_method }
+      p.calls.must_equal(9)
+    end
+
+    it 'should support recursive methods' do
+      p = Frequent.instrument('Potato.recursive_class_method')
+      Potato.recursive_class_method(7)
+      p.calls.must_equal(7)
+    end
+  end
+
+  describe 'probe removal' do
+    it 'should remove probes on instance methods' do
+      p = Frequent.instrument('Potato#instance_method')
+      Potato.new.instance_method
+      p.disable!
+      Potato.new.instance_method
+      p.calls.must_equal(1)
+    end
+
+    it 'should remove probes on class methods' do
+      p = Frequent.instrument('Potato.class_method')
+      Potato.class_method
+      p.disable!
+      Potato.class_method
+      p.calls.must_equal(1)
+    end
+
+    it 'should instrument scoped to block' do
+      p = Frequent.instrument('Potato#instance_method') do
+        5.times { Potato.new.instance_method }
+      end
+      3.times { Potato.new.instance_method }
+      p.calls.must_equal(5)
+    end
+  end
+
+  describe 'instrumentation of modules' do
+    it 'should catch module methods even if included after instrumentation' do
+      module Mod1
+        def demo; end
+      end
+
+      p = Frequent.instrument('Mod1#demo')
+
+      class Dummy1
+        include Mod1
+      end
+      Dummy1.new.demo
+
+      p.calls.must_equal(1)
+    end
+
+    it 'should work if probe placed before module/class definition' do
+      p = Frequent.instrument('Dummy3#foo')
+
+      module Dummy2; def foo; end; end
+      class Dummy3; include Dummy2; end
+
+      10.times { Dummy3.new.foo }
+
+      p.calls.must_equal(10)
+    end
+
+    it 'should work for module methods' do
+      p = Frequent.instrument('Dummy5.foo')
+      module Dummy5; def self.foo; end; end
+      5.times { Dummy5.foo }
+      p.calls.must_equal(5)
+    end
+
+    it 'should work with nested modules' do
+      p = Frequent.instrument('Dummies::Dummy6.foo')
+
+      module Dummies
+        module Dummy6; def self.foo; end; end
+      end
+
+      5.times { Dummies::Dummy6.foo }
+      p.calls.must_equal(5)
+    end
+  end
+
+  it 'should work if method is added to class after instrumentation' do
+    class Dummy7; end
+
+    p = Frequent.instrument('Dummy7#foo')
+
+    class Dummy7; def foo; end; end
+
+    3.times { Dummy7.new.foo }
+    p.calls.must_equal(3)
+  end
+
+  it 'should work for dynamically-created classes' do
+    p = Frequent.instrument('Dummy8.foo')
+
+    eval "class Dummy8; def self.foo; end; end; 5.times { Dummy8.foo }"
+
+    p.calls.must_equal(5)
+  end
+
+  if ENV['BENCH']
+    it 'should be fast' do
+      p = Potato.new
+      n = 1000000
+
+      puts "Trials: #{n}"
+      Benchmark.bmbm do |rpt|
+        rpt.report("Uninstrumented instance method") do
+          n.times { p.instance_method }
+        end
+
+        rpt.report("Instrumented instance method") do
+          Frequent.instrument('Potato#instance_method') do
+            n.times { p.instance_method }
+          end
+        end
+
+        rpt.report("Uninstrumented class method") do
+          n.times { Potato.class_method }
+        end
+        
+        rpt.report("Instrumented class method") do
+          Frequent.instrument("Potato.class_method") do
+            n.times { Potato.class_method }
+          end
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+require 'frequent'
+
+require 'benchmark'
+require 'minitest/autorun'
+require 'minitest/matchers'
+require 'minitest/benchmark' if ENV['BENCH']

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: frequent
+version: !ruby/object:Gem::Version
+  version: '0.1'
+  prerelease: 
+platform: ruby
+authors:
+- Ben Weintraub
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-24 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70106089255840 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70106089255840
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &70106089255400 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70106089255400
+- !ruby/object:Gem::Dependency
+  name: minitest-matchers
+  requirement: &70106089254980 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70106089254980
+description: Ruby method instrumentation demo
+email:
+- benweint@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- frequent.gemspec
+- lib/frequent.rb
+- spec/frequent_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Ruby method instrumentation demo
+test_files:
+- spec/frequent_spec.rb
+- spec/spec_helper.rb