@@ -15,15 +15,20 @@ 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 system with the POSIX call clock_gettime(), -Mac OS X and Windows. +It currently supports any of the following systems: -Using Hitimes can be faster than using a series of Time.new calls, and +* 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. +using +Process.times+. == SYNOPSIS +=== Interval + Use Hitimes::Interval to calculate only the duration of a block of code duration = Hitimes::Interval.measure do @@ -32,21 +37,37 @@ Use Hitimes::Interval to calculate only the duration of a block of code 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' ) @@ -63,6 +84,8 @@ Use a Hitimes::ValueMetric to calculate statistics about measured samples puts value_metric.rate +=== TimedValueMetric + Use a Hitimes::TimedValueMetric to calculate statistics about batches of samples timed_value_metric = Hitimes::TimedValueMetric.new( 'batch times' ) @@ -73,17 +96,17 @@ Use a Hitimes::TimedValueMetric to calculate statistics about batches of samples 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.timed_stats.rate 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 - puts timed_value_metric.value_stats.rate == CHANGES README @@ -1,11 +1,10 @@ Next Release: - timer to_json to report the base stats and the - - add TimedValueMetric + - add string format for stats Future Release: - how to get current timeofday in nanoseconds from all systems - create a pure ruby version - do not blow up on install if unable to compile, fall back to pure ruby version - - add string format for stats - push Timer down to C level TODO.taskpaper @@ -254,6 +254,9 @@ VALUE hitimes_interval_stop_instant( VALUE self ) /** * call-seq: * interval.duration -> Float + * interval.to_f -> Float + * interval.to_seconds -> Float + * interval.length -> Float * * Returns the Float value of the interval, the value is in seconds. If the * interval has not had stop called yet, it will report the number of seconds @@ -321,10 +324,10 @@ void Init_hitimes_interval() rb_define_module_function( cH_Interval, "now", hitimes_interval_now, 0 ); /* in hitimes_interval.c */ rb_define_module_function( cH_Interval, "measure", hitimes_interval_measure, 0 ); /* in hitimes_interval.c */ - rb_define_method( cH_Interval, "to_f", hitimes_interval_duration, 0 ); /* in hitimes_interval.c */ - rb_define_method( cH_Interval, "to_seconds", hitimes_interval_duration, 0 ); /* in hitimes_interval.c */ rb_define_method( cH_Interval, "duration", hitimes_interval_duration, 0 ); /* in hitimes_interval.c */ - rb_define_method( cH_Interval, "length", hitimes_interval_duration, 0 ); /* in hitimes_interval.c */ + rb_define_method( cH_Interval, "length", hitimes_interval_duration, 0 ); + rb_define_method( cH_Interval, "to_f", hitimes_interval_duration, 0 ); + rb_define_method( cH_Interval, "to_seconds", hitimes_interval_duration, 0 ); rb_define_method( cH_Interval, "started?", hitimes_interval_started, 0 ); /* in hitimes_interval.c */ rb_define_method( cH_Interval, "running?", hitimes_interval_running, 0 ); /* in hitimes_interval.c */ ext/hitimes_interval.c @@ -227,8 +227,8 @@ VALUE hitimes_stats_stddev ( VALUE self ) * The Stats class encapulsates capturing and reporting statistics. It is * modeled after the RFuzz::Sampler class, but implemented in C. For general use * you allocate a new Stats object, and then update it with new values. The - * Stats object will keep track of the _min_, _max_, _count_ and _sum_ and when - * you want you may also retrieve the _mean_, _stddev_ and _rate_. + * Stats object will keep track of the _min_, _max_, _count_, _sum_ and _sumsq_ + * and when you want you may also retrieve the _mean_, _stddev_ and _rate_. * * this contrived example shows getting a list of all the files in a directory * and running stats on file sizes. ext/hitimes_stats.c @@ -87,7 +87,7 @@ module Hitimes # :call-seq: # timed_metric.start -> nil # - # Start the current timer, if the current timer is already started, then + # Start the current metric, if the current metric is already started, then # this is a noop. # def start @@ -100,10 +100,10 @@ module Hitimes # :call-seq: # timed_metric.stop -> Float or nil # - # Stop the current timed_metric. This updates the stats and removes the current - # interval. If the timer is not running then this is a noop. If the - # timer was stopped then the duration of the last Interval is returned. If - # the timer was already stopped then false is returned. + # Stop the current metric. This updates the stats and removes the current + # interval. If the timer was stopped then the duration of the last Interval + # is returned. If the timer was already stopped then false is returned and + # no stats are updated. # def stop if running? then @@ -138,7 +138,7 @@ module Hitimes # :call-seq: # timed_metric.split -> Float # - # Split the current timed_metric. Essentially, mark a split time. This means + # Split the current TimedMetric. Essentially, mark a split time. This means # stop the current interval and create a new interval, but make sure # that the new interval lines up exactly, timewise, behind the previous # interval. lib/hitimes/timed_metric.rb @@ -26,7 +26,7 @@ module Hitimes # # A TimedValueMetric keeps track of both the time it took to do an operation # and the size of the batch that was operated on. These metrics are kept - # separately as +timed+ and +value+ accessors. + # separately as +timed_stats+ and +value_stats+ accessors. # class TimedValueMetric < Metric # holds all the Timed statistics @@ -38,7 +38,7 @@ module Hitimes class << TimedValueMetric # # :call-seq: - # TimedValueMetric.now -> TimedValueMetric + # TimedValueMetric.now( 'name' ) -> TimedValueMetric # # Return a TimedValueMetric that has been started # @@ -102,16 +102,17 @@ module Hitimes # :call-seq: # timed_value_metric.stop( count ) -> Float or nil # - # Stop the current timed_value_metric. The +count+ parameter must be a + # Stop the current metric. The +count+ parameter must be a # value to update to the _value_ portion of the TimedValueMetric. Generally # this is probably the number of things that were operated upon since # +start+ was invoked. # - # This updates both the _value_ and _timed_ stats and removes the current - # interval. If the metric is stopped then the duration of the last Interval - # is returned. If the metric was already stopped before this call, then - # false is returned and no stats are updated. + # This updates both the +value_stats+ and +timed_stats+ stats and removes + # the current interval. If the metric is stopped then the duration of the + # last Interval is returned. If the metric was already stopped before this + # call, then false is returned and no stats are updated. # + # def stop( value ) if running? then d = current_interval.stop @@ -130,7 +131,7 @@ module Hitimes # # Measure the execution of a block and add those stats to the running stats. # The return value is the return value of the block. A value must be passed - # into _measure()_ to update the _value_ portion of the TimedValueMetric. + # into +measure+ to update the +value_stats+ portion of the TimedValueMetric. # def measure( value, &block ) return_value = nil @@ -147,15 +148,16 @@ module Hitimes # :call-seq: # timed_value_metric.split( value ) -> Float # - # Split the current timed_value_metric. Essentially, mark a split time. - # This means stop the current interval, with the givein +value+ and create a - # new interval, but make sure that the new interval lines up exactly, - # timewise, behind the previous interval. + # Split the current metric. Essentially, mark a split time. This means + # stop the current interval, with the givein +value+ and create a new + # interval, but make sure that the new interval lines up exactly, timewise, + # behind the previous interval. # - # If the timer is running, then split returns the duration of the previous - # interval, i.e. the split-time. If the timer is not running, nothing + # If the metric is running, then split returns the duration of the previous + # interval, i.e. the split-time. If the metric is not running, nothing # happens, no stats are updated, and false is returned. # + # def split( value ) if running? then next_interval = current_interval.split @@ -170,7 +172,7 @@ module Hitimes # # :call-seq: - # timed_value_metric.durnation -> Float + # timed_value_metric.duration -> Float # # The duration of measured time from the metric. # @@ -188,19 +190,19 @@ module Hitimes # the +rate+ for a TimedValueMetric is the (sum of all quantities sampled) / # ( sum of all durations measured ) # - # For example, say you were measuring, using a TimedValueMetric the rate of - # batch job completion. + # For example, say you were measuring, using a TimedValueMetric batch jobs + # that had individual units of work. # # tvm = TimedValueMetric.new( 'some-batch' ) # tvm.start - # # process a batch + # # process a batch of 12 units # duration1 = tvm.stop( 12 ) # # tvm.start - # # process a larger batch + # # process a larger batch of 42 units # duration2 = tvm.stop( 42 ) # - # At this point the rate is calculated as ( 12 + 42 ) / ( duration1 + duration2 ) + # At this point the rate of units per second is calculated as ( 12 + 42 ) / ( duration1 + duration2 ) # # some_batch_rate = tvm.rate # returns ( 34 / ( duration1+duration2 ) ) # lib/hitimes/timed_value_metric.rb @@ -9,8 +9,13 @@ module Hitimes # module Version + # Major version number MAJOR = 1 + + # Minor version number MINOR = 0 + + # Build number BUILD = 0 # @@ -25,7 +30,7 @@ module Hitimes # # :call-seq: - # Version.to_s -> MAJOR.MINOR.BUILD + # Version.to_s -> "MAJOR.MINOR.BUILD" # # Return the version as a String with dotted notation # @@ -43,8 +48,10 @@ module Hitimes { :major => MAJOR, :minor => MINOR, :build => BUILD } end - + # The Version in MAJOR.MINOR.BUILD dotted notation STRING = Version.to_s end + + # The Version in MAJOR.MINOR.BUILD dotted notation VERSION = Version.to_s end lib/hitimes/version.rb 08a45b2553046ddd7b9746d4e8cac7bf51003107 Jeremy Hinegardner jeremy@hinegardner.org http://github.com/copiousfreetime/hitimes/commit/94b5927c2c1b53f57bc70817dcc1487053eadf88 94b5927c2c1b53f57bc70817dcc1487053eadf88 2009-06-12T13:08:38-07:00 2009-06-12T13:08:38-07:00 documentation cleanup 74857f2d3671c0353413b373169122b2faca003b Jeremy Hinegardner jeremy@hinegardner.org