focal_point 0.0.4 → 0.0.5

data/README.rdoc

@@ -1,7 +1,93 @@
 = focal_point
 
+An unobtrusive profiling utility, for ruby, based on {hitimes}[http://github.com/copiousfreetime/hitimes]. 
 
+- hitimes provides excellent timers (low overhead, high resolution)
+- focal_point lets you use them, without polluting the code you're interested in. 
 
+== Usage
+
+1. Tell FocalPoint to watch one or more methods
+2. Execute the methods you're interested in
+3. Ask FocalPoint for a report
+4. Enjoy 
+
+== Usage Example
+
+Given a contrived implementation:
+
+  class Foo
+    def self.bar
+      rand(10).times { sleep(1) }
+    end
+    def bin
+      Foo.bar
+    end
+  end
+
+You're wondering how much time you spend executing Foo.bar?
+
+  # 1. Tell FocalPoint to watch one or more methods
+  require 'foo'
+  require 'focal_point'
+  FocalPoint.watch('Foo.bar') # eg: class method
+  FocalPoint.watch('Foo#bin') # eg: instance method
+
+  # 2. Execute the methods you're interested in
+  rand(10).times { Foo.bar }
+  rand(10).times { Foo.new.bin }
+
+  # 3. Ask FocalPoint to report what happened
+  FocalPoint.report  ## report accepts an IO object, if you want to send it somewhere else.
+
+  # 4. Enjoy.
+  #
+  # You should see something like this in your stdout.
+  #
+  # --------------------------------------------------------------------------------
+  # sum: 7.003960149
+  # name: Foo.bar
+  # sampling_stop_time: 1.26255541894458e+15
+  # sumsq: 25.03019390208
+  # sampling_start_time: 1.26255541194084e+15
+  # rate: 0.285552738372669
+  # max: 4.003211068
+  # mean: 3.5019800745
+  # count: 2
+  # stddev: 0.708847668889441
+  # min: 3.000749081
+  #
+  # --------------------------------------------------------------------------------
+  # sum: 25.003881843
+  # name: Foo#bin
+  # sampling_stop_time: 1.26255621470907e+15
+  # sumsq: 151.046337138512
+  # sampling_start_time: 1.26255618970493e+15
+  # rate: 0.199968950077237
+  # max: 7.001084262
+  # mean: 5.0007763686
+  # count: 5
+  # stddev: 2.54987821742389
+  # min: 1.000180239
+  # additional_data: 
+
+
+== Motivation
+
+This, or variations of it were happening way to often:
+
+  Foo.class_eval do
+    def self.bar_timer
+      @bar_timer ||= Hitimes::TimedMetric.new("Foo#bar")
+    end
+    alias_method :real_bar, :bar
+    def bar *args
+      self.class.bar_timer.start
+      result = real_bar(*args)
+      self.class.bar_timer.stop
+      result
+    end
+  end
 
 == Note on Patches/Pull Requests
  

data/Rakefile

@@ -12,7 +12,7 @@ begin
     gem.authors = ["levicook@gmail.com"]
     gem.add_dependency "hitimes", ">= 1.0.0"
     gem.add_development_dependency "riot", ">= 0"
-    gem.add_development_dependency "yard", ">= 0"
+    # gem.add_development_dependency "yard", ">= 0"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new
@@ -44,11 +44,13 @@ task :test => :check_dependencies
 
 task :default => :test
 
-begin
-  require 'yard'
-  YARD::Rake::YardocTask.new
-rescue LoadError
-  task :yardoc do
-    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
-  end
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "foo #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
 end
+

data/VERSION

@@ -1 +1 @@
-0.0.4
+0.0.5

data/examples/main.rb

@@ -19,11 +19,11 @@ module Quux
 end
 
 
-focal_point('Quux::Foo.bar')
-focal_point('Quux::Foo.bar')
+FocalPoint.watch('Quux::Foo.bar')
+FocalPoint.watch('Quux::Foo.bar')
 
-focal_point('Quux::Foo#bar')
-focal_points('Quux::Foo#bin', 'Quux::Foo#bin=')
+FocalPoint.watch('Quux::Foo#bar')
+FocalPoint.watch('Quux::Foo#bin', 'Quux::Foo#bin=')
 
 
 fail unless Quux::Foo.bar == :bar
@@ -43,5 +43,5 @@ end == :bar
 end
 
 at_exit do
-  FocalPoint.print_timers
+  FocalPoint.report
 end

data/lib/focal_point.rb

@@ -35,24 +35,23 @@ class FocalPoint
     end
   end
 
-  def self.print_timers io=$stdout
-    timers = []
-    ObjectSpace.each_object(FocalPoint) { |fp| timers << fp.timer }
-    timers.compact.sort_by(&:sum).each do |timer|
-      io.puts '-'*80
-      timer.to_hash.each { |k,v| io.puts "#{k}: #{v}" }
-      io.puts
+  class << self
+
+    # FocalPoint.watch("ClassName#instance_method")
+    # FocalPoint.watch("ClassName.class_method")
+    def watch(*targets)
+      targets.each { |t| FocalPoint.new(t) }
     end
-  end
 
-end
+    def report(io=$stdout)
+      timers = []
+      ObjectSpace.each_object(FocalPoint) { |fp| timers << fp.timer }
+      timers.compact.sort_by(&:sum).each do |timer|
+        io.puts '-'*80
+        timer.to_hash.each { |k,v| io.puts "#{k}: #{v}" }
+        io.puts
+      end
+    end
 
-# call-seq:
-#
-#  focal_point("ClassName#instance_method", ...)
-#  focal_point("ClassName.class_method", ...)
-#
-def focal_point(*targets)
-  targets.each { |t| FocalPoint.new(t) }
+  end
 end
-alias :focal_points :focal_point

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: focal_point
 version: !ruby/object:Gem::Version 
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors: 
 - levicook@gmail.com
@@ -32,16 +32,6 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
     version: 
-- !ruby/object:Gem::Dependency 
-  name: yard
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-    version: 
 description: instruments methods with hitimes
 email: levicook@gmail.com
 executables: []
@@ -52,7 +42,6 @@ extra_rdoc_files:
 - LICENSE
 - README.rdoc
 files: 
-- .document
 - .gitignore
 - LICENSE
 - README.rdoc

data/.document

@@ -1,5 +0,0 @@
-README.rdoc
-lib/**/*.rb
-bin/*
-features/**/*.feature
-LICENSE