1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
# Hitimes
[](https://copiousfreetime.semaphoreci.com/projects/hitimes)
* [Homepage](http://github.com/copiousfreetime/hitimes)
* [Github project](http://github.com/copiousfreetime/hitimes)
## DESCRIPTION
A fast, high resolution timer library for recording performance metrics.
## TABLE OF CONTENTS
* [Requirements](#requirements)
* [Usage](#usage)
* [Contributing](#contributing)
* [Support](#support)
* [License](#license)
## REQUIREMENTS
Hitimes requires the following to run:
* Ruby
## USAGE
Hitimes easiest to use when installed with `rubygems`:
```sh
gem install hitimes
```
Or as part of your bundler `Gemfile`:
```ruby
gem "hitimes"
```
You can load it with the standard ruby require statement.
```ruby
require "hitimes"
```
### Interval
Use `Hitimes::Interval` to calculate only the duration of a block of code.
Returns the time as seconds.
```ruby
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
```ruby
timed_metric = Hitimes::TimedMetric.new("operation on items")
```
Explicitly use `start` and `stop`:
```ruby
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.
```ruby
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
```ruby
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.
``` ruby
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.
``` ruby
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](http://semver.org/).
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](CONTRIBUTING.md) for instructions on development
and bug reporting.
## Credits
* [Bruce Williams](https://github.com/bruce) for suggesting the idea.
* [Benoit Daloze](https://github.com/eregon) and [Thomas Hurst](https://github.com/Freaky) for conversations around clock_ids.
## License
Hitimes is licensed under the [ISC](https://opensource.org/licenses/ISC)
license.
## Related Works
* [monotime](https://github.com/Freaky/monotime) - A sensible interface to Ruby's monotonic clock.
* [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) - [Concurrent.monotonic_time](https://github.com/ruby-concurrency/concurrent-ruby) is a straight pass through to `Process.clock_gettime(Process::CLOCK_MONOTONIC,...)`.
* [Instant](https://doc.rust-lang.org/src/std/time.rs.html) - The rust equivalent.
* [time.Now](https://pkg.go.dev/time) - The go monotonic time interface is part of this package.
|
