stickshift 0.1

data/History.txt

@@ -0,0 +1,3 @@
+== 0.1
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+# (c) Copyright 2008 Nick Sieger <nicksieger@gmail.com>
+# 
+# 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/Manifest.txt

@@ -0,0 +1,11 @@
+examples/example.rake
+examples/stickshift_rails.rb
+History.txt
+lib/stickshift/version.rb
+lib/stickshift.rb
+LICENSE.txt
+Manifest.txt
+Rakefile
+README.markdown
+stickshift.gemspec
+test/test_stickshift.rb

data/README.markdown

@@ -0,0 +1,75 @@
+Stickshift is a simple, manual-instrumenting call-tree profiler in as
+few lines of code as possible.
+
+## Background
+
+The idea is to be as minimally intrusive as possible, but also to be
+stupid simple and manual. You tell stickshift to only instrument the
+methods you want, and it measures time spent in that method, as well
+as any time spent in any instrumented methods invoked by the method.
+After leaving the top-most method, a call tree with timings is dumped
+to $stdout.
+
+Note: You aren't allowed to instrument methods on the String class, or any
+object's #inspect method, because it can generate a recursive loop! For
+#fine-grained profiling on any arbitrary class, use profiler or ruby-prof
+instead. You're also not allowed to instrument an instrumented method.
+
+## Example
+
+Consider the following Rakefile:
+
+    task :sleep => :snooze do
+      sleep 1
+    end
+    task :snooze do
+      sleep 2
+    end
+    task :default => :sleep
+
+    require 'stickshift'
+    ::Rake::Application.instrument :top_level
+    ::Rake::Application.instrument :[], :with_args => 0
+    ::Rake::Task.instrument :invoke, :execute, :inspect_self => true
+
+Running 'rake' will produce the following output. Method self time is
+shown along the left, while method total time is at the end of each
+line.
+
+       0ms >  Rake::Application#top_level < 3001ms
+       0ms >    Rake::Application#[]("default") < 0ms
+       0ms >    Rake::Task#invoke{<Rake::Task default => [sleep]>} < 3001ms
+       0ms >      Rake::Application#[]("sleep") < 0ms
+       0ms >      Rake::Application#[]("snooze") < 0ms
+    2000ms >      Rake::Task#execute{<Rake::Task snooze => []>} < 2000ms
+    1000ms >      Rake::Task#execute{<Rake::Task sleep => [snooze]>} < 1000ms
+       0ms >      Rake::Task#execute{<Rake::Task default => [sleep]>} < 0ms
+
+## Instrumentation
+
+Stickshift adds a method named #instrument to the Module class that
+instruments methods in the receiver module or class.
+
+It accepts one or more method names, and an optional trailing hash of
+options:
+
+* `:label => "label"` gives the instrumented method a custom label
+  instead of the default "Class#method" label.
+* `:with_args => 0` causes the first argument to the method to be
+  included in the label. Ranges can also be used.
+* `:inspect_self => true` causes the inspected object to be printed in
+  the label.
+* `:top_level => true` causes Stickshift to only be activated after
+  passing through this method. If any other non-top-level instrumented
+  method is called outside of a top-level method, it will not be timed
+  or reported.
+
+`#uninstrument` and `#uninstrument_all` methods are also available if
+you wish to disable instrumentation.
+
+## Capture/Settings
+
+* `Stickshift.enabled` (default `true`) controls whether Stickshift is
+  on or not.
+* `Stickshift.output` (default `$stdout`) controls where output is
+  written. The object must respond to `#puts(*lines)`.

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rake/testtask'
+
+begin
+  require 'hoe'
+  Hoe.plugin :rubyforge
+  hoe = Hoe.spec("stickshift") do |p|
+    require File.dirname(__FILE__) + '/lib/stickshift/version'
+    p.version = Stickshift::VERSION
+    p.rubyforge_name = "caldersphere"
+    p.url = "http://caldersphere.rubyforge.org/stickshift"
+    p.readme_file = "README.markdown"
+    p.author = "Nick Sieger"
+    p.email = "nick@nicksieger.com"
+    p.summary = "Stickshift is a pedal-to-the-metal manual profiler."
+    p.description = "Stickshift is a simple, manual-instrumenting call-tree profiler in as few lines of code as possible."
+  end
+
+  task :gemspec do
+    File.open("#{hoe.name}.gemspec", "w") {|f| f << hoe.spec.to_ruby }
+  end
+  task :package => :gemspec
+rescue LoadError
+  puts "You need hoe installed to be able to package this gem"
+end
+
+# Hoe has its own test, but I want Rake::TestTask
+Rake::Task['test'].send :instance_variable_set, "@actions", []
+Rake::TestTask.new
+
+task :default => :test
+
+desc "Run the instrumented rake example"
+task :example do
+  puts "# Here is the example Rakefile"
+  puts *(File.readlines("examples/example.rake"))
+  puts "# Running it"
+  ruby "-Ilib -S rake -f examples/example.rake"
+end

data/examples/example.rake

@@ -0,0 +1,12 @@
+task :sleep => :snooze do
+  sleep 1
+end
+task :snooze do
+  sleep 2
+end
+task :default => :sleep
+
+require 'stickshift'
+::Rake::Application.instrument :top_level
+::Rake::Application.instrument :[], :with_args => 0
+::Rake::Task.instrument :invoke, :execute, :inspect_self => true

data/examples/stickshift_rails.rb

@@ -0,0 +1,34 @@
+# Instrument some of the main methods hit during a Rails request dispatch.
+# Put stickshift.rb in the 'lib' directory of your rails app and this file
+# in the config/initializers directory.
+
+require 'stickshift'
+require 'dispatcher'
+require 'action_controller'
+
+class << Dispatcher; instrument :dispatch, :label => "Rails Dispatcher", :top_level => true; end
+class << ActionController::Base; instrument :process; end
+ActionController::Base.instrument :default_render, :respond_to
+ActionController::Base.instance_methods.select {|m| m =~ /^(process|perform_action)/ }.each do |m|
+  ActionController::Base.instrument m
+end
+ActionController::Base.private_instance_methods.select {|m| m =~ /^(process|perform_action)/ }.each do |m|
+  ActionController::Base.instrument m
+end
+ObjectSpace.each_object(Class) do |klazz|
+  klazz.instrument :run, :call, :inspect_self => true if klazz < ActionController::Filters::ClassMethods::Filter
+end
+ActionController::Base.instance_methods.select {|m| m =~ /^render/ }.each do |m|
+  ActionController::Base.instrument m, :with_args => 0
+end
+ActionController::Routing::RouteSet.instrument :recognize
+ActionView::Base.instrument :render
+
+class << ActiveRecord::Base; instrument :find; end
+ActiveRecord::Base.instrument :save
+ActiveRecord::ConnectionAdapters.constants.each do |c|
+  adapter_class = ActiveRecord::ConnectionAdapters.const_get(c)
+  if adapter_class < ActiveRecord::ConnectionAdapters::AbstractAdapter
+    adapter_class.instrument :execute, :with_args => 0
+  end
+end

data/lib/stickshift.rb

@@ -0,0 +1,142 @@
+module Stickshift
+  class << self; attr_accessor :enabled, :top_level_trigger, :output; end
+  @enabled = true
+  @output = $stdout
+
+  class Timer
+    def self.current;         Thread.current['__stickshift']; end
+    def self.current=(timer); Thread.current['__stickshift'] = timer; end
+    attr_reader :depth
+
+    def initialize(obj, meth, options, *args)
+      @depth, @options, @args = 1, options, args
+      @label = if @options[:label]
+        @options[:label]
+      else
+        klass = Class === obj ? "#{obj.name}." : "#{obj.class.name}#"
+        "#{klass}#{meth}"
+      end
+      @label << "{#{obj.inspect}}"                         if @options[:inspect_self]
+      @label << "(#{@args[@options[:with_args]].inspect})" if @options[:with_args]
+      if @parent = Timer.current
+        @parent.add(self)
+        @depth = @parent.depth + 1
+      end
+    end
+
+    def enabled?
+     Stickshift.enabled && (Timer.current || Stickshift.top_level_trigger.nil? || @options[:top_level])
+    end
+
+    def invoke(&block)
+      return block.call unless enabled?
+      begin
+        Timer.current = self
+        result = nil
+        @elapsed = realtime do
+          result = block.call
+        end
+        result
+      ensure
+        Timer.current = @parent
+        report unless @parent
+      end
+    end
+
+    def realtime
+      start = Time.now
+      yield
+      Time.now - start
+    end
+
+    def add(child)
+      children << child
+    end
+
+    def children
+      @children ||= []
+    end
+
+    def elapsed
+      @elapsed ||= 0
+    end
+
+    def report
+      Stickshift.output.puts "#{self_format % self_time}ms >#{'  ' * @depth}#{@label} < #{total_time}ms"
+      children.each {|c| c.report}
+    end
+
+    def ms(t)
+      (t * 1000)
+    end
+
+    def self_format
+      @self_format ||= if @parent
+        @parent.self_format
+      else
+        width = ("%0.2f" % total_time).length
+        "%#{width}.2f"
+      end
+    end
+
+    def self_time
+      @self_time ||= ms(elapsed - children.inject(0) {|sum,el| sum += el.elapsed})
+    end
+
+    def total_time
+      ms(elapsed)
+    end
+  end
+end
+
+class Module
+  def instrument(*meths)
+    options = Hash === meths.last ? meths.pop : {}
+    Stickshift.top_level_trigger = true if options[:top_level]
+    @__stickshift ||= {}
+    meths.each do |meth|
+      unless instrumented?(meth)
+        mangled   = __stickshift_mangle(meth)
+        meth_opts = options.merge(:original => meth)
+        @__stickshift[mangled] = meth_opts
+        define_method("#{mangled}__instrumented") { meth_opts }
+        alias_method "#{mangled}__orig_instrument", meth
+        alias_method "#{mangled}__without_instrument", meth
+        module_eval(<<-METH, __FILE__, __LINE__)
+          def #{meth}(*args, &block)
+            Stickshift::Timer.new(self, "#{meth}", #{mangled}__instrumented, *args).invoke do
+              #{mangled}__without_instrument(*args, &block)
+            end
+          end
+        METH
+      end
+    end
+  end
+
+  RESTRICTED_CLASSES = [String]
+  RESTRICTED_METHODS = %w(inspect __send__ __id__)
+
+  def instrumented?(meth)
+    RESTRICTED_CLASSES.include?(self) ||
+      RESTRICTED_METHODS.include?(meth.to_s) ||
+      meth =~ /__instrumented$/ ||
+      instance_methods.include?("#{__stickshift_mangle(meth)}__instrumented")
+  end
+
+  def uninstrument(*meths)
+    meths.each do |meth|
+      if instrumented?(meth)
+        remove_method "#{__stickshift_mangle(meth)}__instrumented"
+        alias_method meth, "#{__stickshift_mangle(meth)}__orig_instrument"
+      end
+    end
+  end
+
+  def uninstrument_all
+    uninstrument(*(instance_methods.select {|m| m =~ /__instrumented$/}.map {|mi| @__stickshift[mi[0...-14]][:original]}))
+  end
+
+  def __stickshift_mangle(meth)
+    (s = meth.to_s) =~ /^[a-zA-Z_][a-zA-Z0-9_]*$/ ? s : "_#{s.unpack("H*")[0]}"
+  end
+end

data/lib/stickshift/version.rb

@@ -0,0 +1,3 @@
+module Stickshift
+  VERSION = "0.1"
+end

data/stickshift.gemspec

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{stickshift}
+  s.version = "0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Nick Sieger"]
+  s.date = %q{2011-04-25}
+  s.description = %q{Stickshift is a simple, manual-instrumenting call-tree profiler in as few lines of code as possible.}
+  s.email = %q{nick@nicksieger.com}
+  s.extra_rdoc_files = ["History.txt", "LICENSE.txt", "Manifest.txt"]
+  s.files = ["examples/example.rake", "examples/stickshift_rails.rb", "History.txt", "lib/stickshift/version.rb", "lib/stickshift.rb", "LICENSE.txt", "Manifest.txt", "Rakefile", "README.markdown", "stickshift.gemspec", "test/test_stickshift.rb", ".gemtest"]
+  s.homepage = %q{http://caldersphere.rubyforge.org/stickshift}
+  s.rdoc_options = ["--main", "README.markdown"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{caldersphere}
+  s.rubygems_version = %q{1.5.1}
+  s.summary = %q{Stickshift is a pedal-to-the-metal manual profiler.}
+  s.test_files = ["test/test_stickshift.rb"]
+
+  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_development_dependency(%q<rubyforge>, [">= 2.0.4"])
+      s.add_development_dependency(%q<hoe>, [">= 2.9.4"])
+    else
+      s.add_dependency(%q<rubyforge>, [">= 2.0.4"])
+      s.add_dependency(%q<hoe>, [">= 2.9.4"])
+    end
+  else
+    s.add_dependency(%q<rubyforge>, [">= 2.0.4"])
+    s.add_dependency(%q<hoe>, [">= 2.9.4"])
+  end
+end

data/test/test_stickshift.rb

@@ -0,0 +1,158 @@
+require 'test/unit'
+require 'stringio'
+require 'stickshift'
+
+class Foo
+  def slow_method
+    sleep 0.1
+  end
+  def hello
+  end
+end
+
+class Bar
+  def slow_method
+    call_foo
+  end
+
+  def call_foo
+    Foo.new.slow_method
+  end
+
+  def several_times
+    10.times do
+      slow_method
+    end
+  end
+
+  def call(*args)
+  end
+end
+
+module TestHelper
+  def instrumented_name(meth)
+    Module.__stickshift_mangle(meth) + '__instrumented'
+  end
+  module_function :instrumented_name
+end
+
+class StickshiftTest < Test::Unit::TestCase
+  include TestHelper
+
+  def capture
+    Stickshift.output = @stdout = StringIO.new
+    @out = nil
+  end
+  
+  def teardown
+    Foo.uninstrument_all
+    Bar.uninstrument_all
+    Array.uninstrument_all
+    String.uninstrument_all
+    puts @out if @out
+    Stickshift.top_level_trigger = nil
+    Stickshift.output = $stdout
+  end
+
+  def test_formatting
+    Bar.instrument :slow_method, :several_times
+    Foo.instrument :slow_method
+    Bar.new.several_times
+  end
+
+  def test_output_profile
+    Bar.instrument :slow_method
+    Foo.instrument :slow_method
+    capture
+    Bar.new.slow_method
+    out = @stdout.string
+    assert out =~ /Bar#slow_method/
+    assert out =~ /Foo#slow_method/
+  end
+
+  def test_custom_label
+    capture
+    Foo.instrument :hello, :label => "Hello World!"
+    Foo.new.hello
+    assert @stdout.string =~ /Hello World!/
+  end
+
+  def test_instrument_uninstrument
+    capture
+    Foo.new.hello
+    assert @stdout.string.empty?
+    Foo.instrument :hello
+    Foo.new.hello
+    assert @stdout.string =~ /Foo#hello/
+    @stdout.string = ''
+    Foo.uninstrument :hello
+    Foo.new.hello
+    assert @stdout.string.empty?
+  end
+
+  def test_instrument_with_first_arg
+    capture
+    Bar.instrument :call, :with_args => 0
+    Bar.new.call("abc")
+    Bar.new.call("def")
+    assert @stdout.string =~ /call.*"abc"/
+    assert @stdout.string =~ /call.*"def"/
+  end
+
+  def test_instrument_operator_method
+    capture
+    Array.instrument :<<
+    [] << 1
+    assert @stdout.string =~ /<</
+  end
+
+  def test_instrument_label_self_inspect
+    capture
+    Array.instrument :length, :inspect_self => true
+    %w(a b c).length
+    assert @stdout.string =~ /"a", "b", "c"/
+  end
+
+  def test_output_only_when_triggered_by_top_level_method
+    capture
+    Foo.instrument :slow_method
+    Bar.instrument :slow_method
+    Bar.new.slow_method
+
+    assert !@stdout.string.empty?
+    expected = @stdout.string
+    @stdout.reopen(StringIO.new)
+    assert @stdout.string.empty?
+
+    Bar.uninstrument :slow_method
+    Bar.instrument :slow_method, :top_level => true
+    assert Stickshift.top_level_trigger
+
+    Foo.new.slow_method
+    assert @stdout.string.empty?
+
+    Bar.new.slow_method
+    assert @stdout.string =~ /Bar#slow_method.*Foo#slow_method/m
+  end
+
+  def test_cannot_instrument_instrumented_methods
+    Foo.instrument :slow_method
+    assert Foo.instrumented?(:slow_method)
+    instrumented = instrumented_name(:slow_method)
+    assert Foo.instance_methods.include?(instrumented)
+    Foo.instrument instrumented
+    assert !Foo.instance_methods.include?(instrumented_name(instrumented))
+  end
+
+  def test_cannot_instrument_restricted_methods
+    [:inspect, :__send__, :__id__].each do |m|
+      Foo.instrument m
+      assert !Foo.instance_methods.include?(instrumented_name(m))
+    end
+  end
+
+  def test_cannot_instrument_string_or_benchmark_methods
+    String.instrument :to_s
+    assert !String.instance_methods.include?(instrumented_name(:to_s))
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: stickshift
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: "0.1"
+platform: ruby
+authors: 
+  - Nick Sieger
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-25 00:00:00 -05:00
+default_executable: 
+dependencies: 
+  - !ruby/object:Gem::Dependency 
+    name: rubyforge
+    prerelease: false
+    requirement: &id001 !ruby/object:Gem::Requirement 
+      none: false
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            version: 2.0.4
+    type: :development
+    version_requirements: *id001
+  - !ruby/object:Gem::Dependency 
+    name: hoe
+    prerelease: false
+    requirement: &id002 !ruby/object:Gem::Requirement 
+      none: false
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            version: 2.9.4
+    type: :development
+    version_requirements: *id002
+description: Stickshift is a simple, manual-instrumenting call-tree profiler in as few lines of code as possible.
+email: nick@nicksieger.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+  - History.txt
+  - LICENSE.txt
+  - Manifest.txt
+files: 
+  - examples/example.rake
+  - examples/stickshift_rails.rb
+  - History.txt
+  - lib/stickshift/version.rb
+  - lib/stickshift.rb
+  - LICENSE.txt
+  - Manifest.txt
+  - Rakefile
+  - README.markdown
+  - stickshift.gemspec
+  - test/test_stickshift.rb
+  - .gemtest
+has_rdoc: true
+homepage: http://caldersphere.rubyforge.org/stickshift
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+  - --main
+  - README.markdown
+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: caldersphere
+rubygems_version: 1.5.1
+signing_key: 
+specification_version: 3
+summary: Stickshift is a pedal-to-the-metal manual profiler.
+test_files: 
+  - test/test_stickshift.rb