Hitimes
¶ ↑
DESCRIPTION¶ ↑
A fast, high resolution timer library for recording performance metrics.
TABLE OF CONTENTS¶ ↑
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.