copiousfreetime / hitimes

== 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.