Hitimes

• Homepage
• Github project

DESCRIPTION

A fast, high resolution timer library for recording performance metrics.

TABLE OF CONTENTS

• Requirements
• Usage
• Contributing
• Support
• License

REQUIREMENTS

Hitimes requires the following to run:

• Ruby

USAGE

Hitimes easiest to use when installed with rubygems:

gem install hitimes

Or as part of your bundler Gemfile:

gem "hitimes"

You can load it with the standard ruby require statement.

require "hitimes"

Interval

Use Hitimes::Interval to calculate only the duration of a block of code. Returns the time as seconds.

duration = Hitimes::Interval.measure do
  1_000_000.times do |x|
    2 + 2
  end
end

puts duration  # => 0.047414297 (seconds)

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) }
  # do something with result_of_do_something
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

Implementation details

Hitimes uses the internal ruby Process::clock_gettime() to get the highest granularity time increment possible. Generally this is nanosecond resolution, or whatever the hardware in the CPU supports.

SUPPORT

Hitimes is supported on whatever versions of ruby are currently supported. Hitimes also follows semantic versioning.

The current officially supported versions of Ruby are:

• MRI Ruby (all platforms) 3.0 - current
• JRuby 9.4.x.x
• Truffleruby 24

Unofficially supported versions, any version of MRI from Ruby 2.1 and up. Since the C Extension has been removed Hitimes should work with any ruby that is 2.1 or greater as that is when Process.clock_gettime() was implemented.

For versions of Ruby before 2.1 please use Hitimes 1.3, the extension code is still in there and they should still work.

CONTRIBUTING

Please read CONTRIBUTING.md for instructions on development and bug reporting.

Credits

• Bruce Williams for suggesting the idea.
• Benoit Daloze and Thomas Hurst for conversations around clock_ids.

License

Hitimes is licensed under the ISC license.

Related Works

• monotime - A sensible interface to Ruby's monotonic clock.
• concurrent-ruby - Concurrent.monotonic_time is a straight pass through to Process.clock_gettime(Process::CLOCK_MONOTONIC,...).
• Instant - The rust equivalent.
• time.Now - The go monotonic time interface is part of this package.