hitimes 1.1.0-java

data/HISTORY

@@ -0,0 +1,69 @@
+= Changelog
+== Version 1.1.0 2010-07-28
+
+* Add a pure java extension so hitimes may be used in jruby with the same API
+
+== Version 1.0.5 2010-07-20
+
+* Fix 'circular require considered harmful' warnings in 1.9.x (reported by Roger Pack)
+* Fix 'method redefined' warnings in 1.9.x (reported by Roger Pack)
+
+== Version 1.0.4 2009-08-01
+
+* Add in support for x86-mingw32 gem
+* Add version subdirectory for extension on all platforms
+
+== Version 1.0.3 2009-06-28
+
+* Fix bug with time.h on linode (reported by Roger Pack) 
+* Fix potential garbage collection issue with Interval class
+* Windows gem is now a fat binary to support installing in 1.8 or 1.9 from the
+  same gem
+
+== Version 1.0.1 2009-06-12
+
+* Fix examples
+* performance tuning, new Hitimes::Metric derived classes are faster than old Timer class
+
+== Version 1.0.0 2009-06-12
+
+* Major version bump with complete refactor of the metric collection API
+* 3 types of metrics now instead of just 1 Timer
+  * Hitimes::ValueMetric
+  * Hitimes::TimedMetric
+  * Hitimes::TimedValueMetric
+* The ability to convert all metrics #to_hash
+* Updated documentation with examples using each metric type
+
+== Version 0.4.1 2009-02-19
+
+* change to ISC License
+* fix bug in compilation on gentoo
+
+== Version 0.4.0 2008-12-20
+
+* Added new stat 'rate'
+* Added new stat method to_hash
+* Added Hitimes::MutexedStats class for threadsafe stats collection 
+  - not needed when used in MRI 1.8.x
+* remove stale dependency on mkrf
+
+== Version 0.3.0
+
+* switched to extconf for building extensions
+* first release of windows binary gem
+* reverted back to normal rdoc
+
+== Version 0.2.1
+
+* added Timer#rate method
+* switched to darkfish rdoc
+
+== Version 0.2.0
+
+* Performance improvements
+* Added Hitimes::Stats class
+
+== Version 0.1.0
+
+* Initial completion

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2008 Jeremy Hinegardner
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

data/README

@@ -0,0 +1,134 @@
+== hitimes
+
+* Homepage[http://copiousfreetime.rubyforge.org/hitimes] 
+* {Rubyforge project}[http://rubyforge.org/projects/copiousfreetime/]
+* email jeremy at copiousfreetime dot org
+* git clone url git://github.com/copiousfreetime/hitimes.git
+
+== INSTALL
+
+* gem install hitimes
+
+== DESCRIPTION
+
+Hitimes is a fast, high resolution timer library for recording
+performance metrics.  It uses the appropriate C method calls for each
+system to get the highest granularity time increments possible.  
+
+It currently supports any of the following systems:
+
+* any system with the POSIX call <tt>clock_gettime()</tt>,
+* Mac OS X
+* Windows
+
+Using Hitimes can be faster than using a series of +Time.new+ calls, and
+it will have a much higher granularity.   It is definitely faster than
+using +Process.times+. 
+
+== SYNOPSIS
+
+=== Interval
+
+Use Hitimes::Interval to calculate only the duration of a block of code
+
+  duration = Hitimes::Interval.measure do
+               # some operation ...
+             end
+
+  puts duration   
+
+=== TimedMetric
+
+Use a Hitimes::TimedMetric to calculate statistics about an iterative operation
+
+  timed_metric = Hitimes::TimedMetric.new('operation on items')
+
+Explicitly use +start+ and +stop+:
+
+  collection.each do |item|
+    timed_metric.start
+    # .. do something with item
+    timed_metric.stop
+  end
+
+Or use the block.  In TimedMetric the return value of +measure+ is the return
+value of the block
+
+  collection.each do |item|
+    result_of_do_something = timed_metric.measure { do_something( item ) }
+  end
+
+And then look at the stats
+
+  puts timed_metric.mean
+  puts timed_metric.max
+  puts timed_metric.min
+  puts timed_metric.stddev
+  puts timed_metric.rate
+
+=== ValueMetric 
+
+Use a Hitimes::ValueMetric to calculate statistics about measured samples
+
+  value_metric = Hitimes::ValueMetric.new( 'size of thing' )
+  loop do
+    # ... do stuff changing sizes of 'thing'
+    value_metric.measure( thing.size )
+    # ... do other stuff that may change size of thing
+  end
+
+  puts value_metric.mean
+  puts value_metric.max
+  puts value_metric.min
+  puts value_metric.stddev
+  puts value_metric.rate
+
+
+=== TimedValueMetric
+
+Use a Hitimes::TimedValueMetric to calculate statistics about batches of samples
+
+  timed_value_metric = Hitimes::TimedValueMetric.new( 'batch times' )
+  loop do 
+    batch = ... # get a batch of things
+    timed_value_metric.start
+    # .. do something with batch
+    timed_value_metric.stop( batch.size )
+  end
+
+  puts timed_value_metric.rate
+
+  puts timed_value_metric.timed_stats.mean
+  puts timed_value_metric.timed_stats.max
+  puts timed_value_metric.timed_stats.min
+  puts timed_value_metric.timed_stats.stddev
+
+  puts timed_value_metric.value_stats.mean
+  puts timed_value_metric.value_stats.max
+  puts timed_value_metric.value_stats.min
+  puts timed_value_metric.value_stats.stddev
+
+
+== CHANGES
+
+Read the HISTORY file.
+
+== CREDITS
+
+* Bruce Williams for suggesting the idea
+
+== ISC License
+
+Copyright (c) 2008 Jeremy Hinegardner
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

data/Rakefile

@@ -0,0 +1,66 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+#-------------------------------------------------------------------------------
+# make sure our project's top level directory and the lib directory are added to
+# the ruby search path.
+#-------------------------------------------------------------------------------
+$: << File.expand_path(File.join(File.dirname(__FILE__),"ext"))
+$: << File.expand_path(File.join(File.dirname(__FILE__),"lib"))
+$: << File.expand_path(File.dirname(__FILE__))
+
+
+#-------------------------------------------------------------------------------
+# load the global project configuration and add in the top level clean and
+# clobber tasks so that other tasks can utilize those constants if necessary
+# This loads up the defaults for the whole project configuration
+#-------------------------------------------------------------------------------
+require 'rubygems'
+require 'tasks/config.rb'
+require 'rake/clean'
+
+#-------------------------------------------------------------------------------
+# Main configuration for the project, these overwrite the items that are in
+# tasks/config.rb
+#-------------------------------------------------------------------------------
+require 'hitimes/version'
+require 'hitimes/paths'
+
+Configuration.for("project") {
+  name      "hitimes"
+  version   Hitimes::VERSION
+  author    "Jeremy Hinegardner"
+  email     "jeremy@copiousfreetime.org"
+  homepage  "http://copiousfreetime.rubyforge.org/hitimes/"
+}
+
+#-------------------------------------------------------------------------------
+# load up all the project tasks and setup the default task to be the
+# test:default task.
+#-------------------------------------------------------------------------------
+Configuration.for("packaging").files.tasks.each do |tasklib|
+  import tasklib
+end
+task :default => 'test:default'
+
+#-------------------------------------------------------------------------------
+# Finalize the loading of all pending imports and update the top level clobber
+# task to depend on all possible sub-level tasks that have a name like
+# ':clobber'  in other namespaces.  This allows us to say:
+#
+#   rake clobber
+#
+# and it will get everything.
+#-------------------------------------------------------------------------------
+Rake.application.load_imports
+Rake.application.tasks.each do |t| 
+  if t.name =~ /:clobber/ then
+    task :clobber => [t.name] 
+  end 
+  if t.name =~ /:clean/ then
+    task :clean => [t.name]
+  end
+end
+

data/examples/benchmarks.rb

@@ -0,0 +1,113 @@
+require 'benchmark'
+require 'time'
+
+#
+# this is all here in case this example is run from the examples directory
+#
+begin
+  require 'hitimes'
+rescue LoadError => le
+  ext_path = File.expand_path( File.join( File.dirname( __FILE__ ), "..", "ext" ) )
+  lib_path = File.expand_path( File.join( File.dirname( __FILE__ ), "..", "lib" ) )
+  if $:.include?( ext_path ) then
+    raise le
+  end
+  $: << ext_path
+  $: << lib_path
+  retry
+end
+
+#----------------------------------------------------------------------
+# test program to look at the performance sampling time durations using
+# different methods
+#----------------------------------------------------------------------
+
+include Benchmark
+
+#
+# Normal apprach to Interval usage
+#
+def hitimes_duration_i1
+  i = Hitimes::Interval.new
+  i.start
+  i.stop
+end
+
+#
+# Use the easy access method to start stop an interval
+#
+def hitimes_duration_i2
+  Hitimes::Interval.now.stop
+end
+
+#
+# Use a new timer each time
+#
+def hitimes_duration_t1
+  Hitimes::TimedMetric.now('duration_t1').stop
+end
+
+#
+# reuse the same timer over and over
+#
+HT2= Hitimes::TimedMetric.new( 'duration_t2' )
+def hitimes_duration_t2
+  HT2.start
+  HT2.stop
+end
+
+HT3 = Hitimes::TimedMetric.new( 'duration_t3' )
+def hitimes_duration_t3
+  HT3.measure { nil }
+end
+
+#
+# Check out the speed of the TimedValueMetric too
+#
+def hitimes_duration_tv1
+  Hitimes::TimedValueMetric.now( 'duration_tv1' ).stop( 42 )
+end
+
+HTV2 = Hitimes::TimedValueMetric.new( 'duration_tv2' )
+def hitimes_duration_tv2
+  HTV2.start
+  HTV2.stop( 42 )
+end
+
+HTV3 = Hitimes::TimedValueMetric.new( 'duration_tv3' )
+def hitimes_duration_tv3
+  HTV3.measure( 42 ) { nil }
+end
+
+#
+# use the Struct::Tms values and return  the difference in User time between 2 
+# successive calls
+#
+def process_duration
+  t1 = Process.times.utime
+  Process.times.utime - t1
+end
+
+#
+# Take 2 times and subtract one from the other
+#
+def time_duration
+  t1 = Time.now.to_f
+  Time.now.to_f - t1
+end
+  
+
+puts "Testing time sampling 100,000 times"
+
+bm(30) do |x|
+  x.report("Process")                     { 100_000.times { process_duration } }
+  x.report("Time")                        { 100_000.times { time_duration    } }
+  x.report("Hitimes::TimedMetric 1")      { 100_000.times { hitimes_duration_t1 } }
+  x.report("Hitimes::TimedMetric 2")      { 100_000.times { hitimes_duration_t2 } }
+  x.report("Hitimes::TimedMetric 3")      { 100_000.times { hitimes_duration_t3 } }
+  x.report("Hitimes::Interval 1")         { 100_000.times { hitimes_duration_i1 } }
+  x.report("Hitimes::Interval 2")         { 100_000.times { hitimes_duration_i2 } }
+  x.report("Hitimes::TimedValueMetric 1") { 100_000.times { hitimes_duration_tv1 } }
+  x.report("Hitimes::TimedValueMetric 2") { 100_000.times { hitimes_duration_tv2 } }
+  x.report("Hitimes::TimedValueMetric 3") { 100_000.times { hitimes_duration_tv3 } }
+end

data/examples/stats.rb

@@ -0,0 +1,31 @@
+#
+# this is all here in case this example is run from the examples directory
+#
+begin
+  require 'hitimes'
+rescue LoadError => le
+  %w[ ext lib ].each do |p|
+    path = File.expand_path( File.join( File.dirname( __FILE__ ), "..", p ) )
+    if $:.include?( path ) then
+      raise le
+    end
+    $: << path
+  end
+  retry
+end
+
+s = Hitimes::Stats.new
+dir = ARGV.shift || Dir.pwd
+Dir.entries( dir ).each do |entry|
+  fs = File.stat( entry )
+  if fs.file? then
+    s.update( fs.size )
+  end
+end
+
+Hitimes::Stats::STATS.each do |m|
+  puts "#{m.rjust(6)} : #{s.send( m ) }"
+end
+
+puts s.to_hash.inspect
+

data/ext/hitimes/extconf.rb

@@ -0,0 +1,17 @@
+require 'rbconfig'
+require 'mkmf'
+
+if Config::CONFIG['host_os'] =~ /darwin/ then
+  $CFLAGS += " -DUSE_INSTANT_OSX=1 -Wall"
+  $LDFLAGS += " -framework CoreServices"
+elsif Config::CONFIG['host_os'] =~ /win32/ or Config::CONFIG['host_os'] =~ /mingw/ then
+  $CFLAGS += " -DUSE_INSTANT_WINDOWS=1"
+else
+  if have_library("rt", "clock_gettime") then
+    $CFLAGS += " -DUSE_INSTANT_CLOCK_GETTIME=1"
+  end
+end
+
+# put in a different location if on windows so we can have fat binaries
+subdir = RUBY_VERSION.gsub(/\.\d$/,'')
+create_makefile("hitimes/#{subdir}/hitimes_ext")