monotonic.rb 0.6.6 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17e3187f97eede654634d62e5eeba6595b19df22dd6e38be3d5a64f5ee9cbc68
-  data.tar.gz: d72962badf2f68b748d8fe48ebab3e3e1fcf78a8a4fd133d3c1bce663459fc5f
+  metadata.gz: 577e4ce149e58981c889c52eaed6256c4c11a5bf2d1e6144513d3cd8c0d72705
+  data.tar.gz: 60b83880903cbe10e28ab23462953ecc6b43296c1c39ae08e5c8cc6442697794
 SHA512:
-  metadata.gz: 74ec59b8280c65b333fd22b4293370784c6756a4980d316700833645f6a67305393a06098ce5d1950c9e4b331049d3662b7fbd1915590cbb40074c1aaafd9217
-  data.tar.gz: 0b31c5c4dad215a636b7053008353af3097db2fbdb0e2fb1654bbf7fd2ed341f065c5a867a9d072c96107d7d9e486458e741e76df012d2cc31cdef941e1b78e0
+  metadata.gz: '084908b43a5095d6ff4a3928a6161abb5800ce113714036afdd3bbc89c361886292c603d2f44bd33014d4fa0c5f8e25779c183933e1c4336c2767991ec21b194'
+  data.tar.gz: 252ba0130e324f322c37cb4df402a307ff534580ff422fc8b7ddbda494b3e8b28d0c681417dde96989d6d8f1d4dc8f2eb6bd5c9847b167b3176295fc88f27561

data/CHANGELOG

@@ -0,0 +1,166 @@
+# CHANGELOG
+
+## 20260811
+
+0.7.0: Read the clock exactly, and read a clock worth reading exactly.
+
+1. ~ lib/Monotonic/Time.rb: Process.clock_gettime is now asked for :nanosecond, where it answers with an Integer, rather than for seconds, where it answers with a Float. A Float's mantissa is of a fixed width wherever it sits, so its absolute resolution falls away as the uptime grows: around 2.2e-16s near 1.0, but only 4.7e-10s at a month of uptime.
+2. + Monotonic::Time#nanoseconds_since_boot: the reading itself, exact.
+3. ~ Monotonic::Time#seconds_since_boot: /attr_reader/derived from the nanosecond reading/, so that the rounding happens where it is asked for rather than where the clock is read. It returns a Float as before.
+4. + Monotonic::NANOSECONDS_PER_SECOND, being needed by both Time and Timer.
+5. + Monotonic::Timer#total_nanoseconds: an elapsed interval as an exact Integer. This is where the reading was formerly spent, an interval being the difference of two Floats drawn from an uptime many orders of magnitude larger than itself.
+6. ~ Monotonic::Timer#total_time: derived from #total_nanoseconds. It returns a Float as before.
+7. ~ Monotonic::Timer#total_time: - the branch upon @finish_time, which moved to a private #finish_nanoseconds, so that the running and stopped cases are distinguished in one place rather than in each caller.
+8. + Monotonic::Timer.clock_name and Monotonic::Time.clock_name, and Monotonic::Timer::CLOCK, being CLOCK_UPTIME_RAW where it is defined and CLOCK_MONOTONIC otherwise. An interval is not an instant and wants a different clock: upon Darwin CLOCK_UPTIME_RAW advances in some 42ns against the 1000ns of CLOCK_MONOTONIC, and holds while the machine sleeps, a closed lid being no part of execution. Linux has no such clock, but its CLOCK_MONOTONIC already holds while suspended and advances finely, so the fallback carries the same meaning and not merely the same name. Exactness alone was worth little upon the old clock, whose 1000ns tick a Float would not have troubled for 142 years of uptime; upon 42ns it begins to tell after six.
+9. ~ Monotonic::Timer: - its use of Monotonic::Time, since the two now read different clocks. @start_time and @finish_time become @start_nanoseconds and @finish_nanoseconds, read through a private #now.
+10. ~ Monotonic::Time::CLOCK, being CLOCK_MONOTONIC still, and now named. #to_time maps an instant back onto the wall clock by way of the boot time, so the clock wanted there is the one tracking time since boot as the wall clock understands it, sleep and all.
+11. + Monotonic::Time.resolution and Monotonic::Timer.resolution, from Process.clock_getres. How finely a clock advances is a property of the processor and the operating system, so it is asked rather than tabulated, and a README sentence about one platform cannot stand in for it. A reading is denominated in nanoseconds whether or not the clock affords them; this is the method which says what a reading is worth.
+12. ~ .clock_name is a method upon both classes rather than a CLOCK_NAME constant, since which clock is read is something found by asking the platform, as .resolution is, and not a property this library declares. A constant would also have frozen a contestable decision: sleep is excluded from a timed interval here, and nothing could have said otherwise. CLOCK stays a constant, being read twice upon every measurement against a floor of some tens of nanoseconds, and is now commented as such.
+13. ~ test/Monotonic/Time_test.rb: ~ the initialize test, which read @seconds_since_boot, to read @nanoseconds_since_boot.
+14. + test/Monotonic/Time_test.rb: tests for .clock_name, .resolution and #nanoseconds_since_boot, and that #seconds_since_boot is that reading expressed in seconds.
+15. + test/Monotonic/Timer_test.rb: tests for #total_nanoseconds, including that it holds while the timer is stopped, and for the clock: which one is chosen, that CLOCK follows .clock_name, that it reports its resolution, and that it is no coarser than the one Monotonic::Time reads.
+16. ~ README.md: + #nanoseconds_since_boot, #total_nanoseconds and .resolution to the description and the usage. The description now distinguishes denomination from resolution, asking for :nanosecond settling only what the figure counts, and points at .resolution rather than making a claim about any one platform.
+17. ~ Monotonic::VERSION: /0.6.7/0.7.0/
+
+
+## 20260716
+
+0.6.7: Block exception bug fix, relicensing, and gem packaging changes.
+
+1. ~ Monotonic::Timer#time: - the `return total_time` from the ensure clause, since returning from an ensure swallowed any exception raised by the block, handing back a duration in place of the error. The exception is now allowed to propagate. The ensure itself is kept, and narrowed to the block, so that stop still runs when the block is interrupted: the time up to an interruption is worth having, and without the stop total_time would go on running rather than hold at the point of interruption. It is read from the timer, since the return value belongs to the exception.
+2. ~ test/Monotonic/Timer_test.rb: + a test to demonstrate that an exception raised within the block is no longer swallowed.
+3. ~ test/Monotonic/Timer_test.rb: + a test to demonstrate that the time up to an interruption holds rather than goes on running.
+4. - test/monotonic_test.rb: A Rakefile has been introduced to run all files.
+5. ~ monotonic.rb.gemspec: /Ruby/MIT/ for the license.
+6. ~ monotonic.rb.gemspec: Gem::Specification#dependencies= and #development_dependencies=, so that dependencies may be enumerated as a list rather than a call apiece.
+7. ~ monotonic.rb.gemspec: spec.files to include CHANGELOG, Gemfile, the gemspec, the Rakefile, README.md and the tests, rather than lib/**/*.rb alone.
+8. ~ monotonic.rb.gemspec: spec.require_paths, since spec.files is no longer confined to lib/.
+9. + monotonic.rb.gemspec: rake as a development dependency.
+10. + Rakefile: a test task, run by default.
+11. ~ lib/Monotonic/Time.rb: - empty lines from within the class body.
+12. ~ lib/Monotonic/Timer.rb: - empty lines from within the class body.
+13. ~ CHANGELOG: Reformat headers, number the changes, and remove `.md`.
+14. ~ Monotonic::VERSION: /0.6.6/0.6.7/
+
+
+## 20260716
+
+0.6.6: Case-sensitive filesystem fixes.
+
+1. ~ lib/monotonic/ --> lib/Monotonic/: the directory was the only reference using lowercase, while the entry require, the test requires and the gemspec all already used Monotonic/, so the published gem failed to load on case-sensitive (Linux) filesystems.
+2. ~ lib/Monotonic/VERSION.rb: /class Monotonic/module Monotonic/ so it matches the module reopened in Time.rb and Timer.rb, rather than raising TypeError when loaded alongside them.
+3. + lib/monotonic.rb: require_relative './Monotonic/VERSION' (as Duration.rb does for its own VERSION), so Monotonic::VERSION is available after requiring the gem. VERSION.rb being off the load path is what let the class/module error above go unnoticed: nothing loaded it alongside Time.rb and Timer.rb, so the conflict never fired.
+
+
+## 20240822
+
+0.6.5: Block usage bug fix
+
+1. ~ lib/monotonic/Timer.rb: The total_time must be explicitly returned since values in ensure are not returned as the default return value.
+
+
+## 20240822
+
+0.6.4: Correct README.md.
+
+1. ~ README.md: In the Usage section: /MonotonicTime/Monotonic::Time/
+2. ~ lib/monotonic/VERSION.rb: 0.6.3 --> 0.6.4 because I mistakenly pulled the 0.6.3 gem.
+
+
+## 20210627
+
+0.6.3: Using gemspec in Gemfile.
+
+1. ~ Gemfile to use gemspec rather than having dependencies enumerated there
+
+
+## 20210625
+
+0.6.2: Fixed missing sys-uptime dependency.
+
+1. ~ montonic.rb.gemspec to include the sys-uptime dependency
+
+
+## 20210623
+
+0.6.1: README fix and a small refactor
+
+1. ~ README.md: /monotonic/monotonic.rb/
+2. ~ Monotonic::Timer.time to make use of the same-named instance method now that it's available.
+
+
+## 20210623
+
+0.6.0: Version number bump due to name change from monotony.rb to monotonic.rb
+
+1. /Monotony//, Monotonic::Timer is shorter than Monotony::MonotonicTimer
+
+
+## 20210607
+
+0.5.0: Added timing block on an instance of MonotonicTimer
+
+1. + MonotonicTime#+
+2. + MonotonicTime#-
+3. ~ MonotonicTimer#start: - use of MonotonicTime#to_time (using MonotonicTime#- instead)
+4. ~ MonotonicTimer#stop: - use of MonotonicTime#to_time (using MonotonicTime#- instead)
+5. + MonotonicTimer#time
+
+
+## 20210607
+
+0.4.1: Fixed starting and stopping
+
+1. - MonotonicTimer#initialize: - @total_time as it just made things more complicated unless needing splits
+2. ~ MonotonicTimer#start: - @start_monotonic_time as it wasn't really needed
+3. ~ MonotonicTimer#stop: - @stop_monotonic_time as it wasn't really needed
+4. ~ MonotonicTimer#total_time: - @total_time as it just made things more complicated unless needing splits
+
+
+## 20210606
+
+0.4.0: Named Monotony and prepped as a gem.
+
+1. /monotonic_time.rb/MonotonicTime.rb/
+2. /monotonic_timer.rb/MonotonicTimer.rb/
+3. + Monotony namespace
+4. + monotony.gemspec
+
+
+## 20210604
+
+0.3.0
+
+1. ~ MonotonicTimer.time, so that it returns the total time to the value of the block
+2. + ./test/monotonic_time_test.rb
+3. ~ ./test/monotonic_timer_test.rb
+
+
+## 20210510
+
+0.2.0: Added somewhat proper testing
+
+1. + ./test/monotonic_timer_test.rb
+2. ~ ./lib/monotonic_timer.rb: - self-run section test
+
+
+## 20200510
+
+0.1.1
+
+1. ~ ./lib/monotonic_timer.rb: + self-run section test
+
+
+## 20200115
+
+0.1.0: Added classes for better structure
+
+1. + MonotonicTime
+2. + MonotonicTimer
+
+
+## 20200115
+
+0.0.0
+
+1. + timer()

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://www.rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,129 @@
+# monotonic.rb
+
+
+## Description
+
+Create accurate timings of excution in Ruby.
+
+What accurate means is to capture many digits as an operating system is willing to afford. Hence, the clock is read in nanoseconds by default. If a number in seconds is requested, then that is derived from nanoseconds rather than read directly, so the rounding happens upon request and not before.
+
+It tells most upon an elapsed interval, that being the difference of two readings drawn from an uptime many orders of magnitude larger than itself. A `Float` carries a mantissa of fixed width wherever it sits, so its absolute resolution falls away as the uptime grows: around 2.2e-16s near 1.0, but only 4.7e-10s after a month of uptime. Differencing two exact integers spends none of the reading, however long the machine has been up.
+
+Which clock is read follows from that. `Monotonic::Timer` measures intervals and so takes the finest available which holds while the machine sleeps, a closed lid being no part of execution: `CLOCK_UPTIME_RAW` upon Darwin, where it advances in some 42ns against the 1000ns of `CLOCK_MONOTONIC`, and `CLOCK_MONOTONIC` elsewhere, which upon Linux already holds while suspended and advances finely. `Monotonic::Time` is an instant rather than an interval, and `#to_time` maps it back onto the wall clock, so it stays upon `CLOCK_MONOTONIC`, sleep and all.
+
+How finely a clock advances is the platform's business and not this library's to claim, so it is asked rather than tabulated:
+
+```ruby
+  Monotonic::Timer.resolution
+  # => 42
+  Monotonic::Time.resolution
+  # => 1000
+```
+
+A reading is denominated in nanoseconds whether or not the clock affords them, so that is the method which says what a reading is worth. Two figures give the sense of it upon the finer clock: reading it costs about 34ns against the 42ns it takes to advance, the two being close enough that there is little to be had by going finer, and a pair of `Float`s would not begin to lose it until some six years of uptime — but they would begin.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+  gem 'monotonic.rb'
+```
+
+And then execute:
+
+```bash
+  $ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+  $ gem install monotonic.rb
+```
+
+
+## Usage
+
+### Monotonic::Time
+
+```ruby
+  require 'monotonic.rb'
+  monotonic_time = Monotonic::Time.new
+  monotonic_time.nanoseconds_since_boot
+  # => 2614365376498000
+  monotonic_time.seconds_since_boot
+  # => 1208799.325906
+  monotonic_time + Monotonic::Time.now
+  # => 2417598.681896
+  monotonic_time - Monotonic::Time.now
+  # => -0.044104999862611294
+  monotonic_time.to_s
+  # => "1164320.268127 seconds since boot."
+  monotonic_time.to_time
+  # => 2021-06-07 09:27:08 8249692651179/8388608000000 +1000
+```
+
+### Monotonic::Timer without a block
+
+```ruby
+  require 'monotonic.rb'
+  timer = Monotonic::Timer.new
+  timer.start
+  i = 0
+  1_000_000.times{puts i += 1}
+  timer.stop
+  timer.total_nanoseconds
+  # => 27734000
+  timer.total_time
+  # => 7.166559999808669
+```
+
+### Monotonic::Timer with a block
+
+```ruby
+  require 'monotonic.rb'
+  time = Monotonic::Timer.time do
+    i = 0
+    1_000_000.times{puts i += 1}
+  end
+  time
+  # => 6.975823000073433
+```
+
+### Monotonic::Timer with a block and block variable
+
+```ruby
+  require 'monotonic.rb'
+  time = Monotonic::Timer.time do |timer|
+    i = 0
+    500_000.times{puts i += 1}
+    p timer.total_time
+    500_000.times{puts i += 1}
+  end
+  time
+  # => 6.975823000073433
+```
+
+### Monotonic::Timer with a block on a timer instance
+
+```ruby
+  require 'monotonic.rb'
+  timer = Monotonic::Timer.new
+  time = timer.time do
+    i = 0
+    1_000_000.times{puts i += 1}
+  end
+  time
+  # => 7.033131000120193
+```
+
+
+## Contributing
+
+1. Fork it ( https://github.com/thoran/monotonic.rb/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new pull request

data/Rakefile

@@ -0,0 +1,9 @@
+# Rakefile
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/lib/Monotonic/Time.rb

@@ -4,38 +4,70 @@
 require 'sys-uptime'
 
 module Monotonic
-  class Time
+  NANOSECONDS_PER_SECOND = 1_000_000_000
 
+  class Time
     class << self
+      # An instant, which #to_time maps back onto the wall clock by way of the
+      # boot time, so the clock wanted here is the one which tracks time since
+      # boot as the wall clock understands it.  That is CLOCK_MONOTONIC, sleep
+      # and all.  Monotonic::Timer measures intervals rather than instants and
+      # chooses a finer clock of its own.
+      #
+      # Unlike Timer's, this one is chosen rather than found, there being no
+      # alternative which would still answer to #to_time.  It is a method all
+      # the same, so that the two classes answer the question alike.
+      def clock_name
+        :CLOCK_MONOTONIC
+      end
 
       def now
         self.new
       end
 
+      # How finely this clock advances, in nanoseconds.  It is asked rather than
+      # tabulated, being a property of the processor and the operating system
+      # and not of this library: upon macOS CLOCK_MONOTONIC answers 1000 here.
+      # A reading is denominated in nanoseconds whatever the answer, so this is
+      # the method which says what a reading is worth.
+      def resolution
+        Process.clock_getres(CLOCK, :nanosecond)
+      end
     end # class << self
 
-    attr_reader :seconds_since_boot
+    # Read upon every instance, so a constant rather than a lookup.  It follows
+    # .clock_name, and so must come after it.
+    CLOCK = Process.const_get(clock_name)
+
+    attr_reader :nanoseconds_since_boot
+
+    # The clock is read in nanoseconds because it answers there with an Integer,
+    # which is exact and stays exact however long the machine has been up.
+    # Seconds are derived rather than read, so that the reading loses nothing and
+    # the rounding happens where it is asked for.
+    def seconds_since_boot
+      @nanoseconds_since_boot / NANOSECONDS_PER_SECOND.to_f
+    end
 
     def initialize
       @boot_time = Sys::Uptime.boot_time
-      @seconds_since_boot = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @nanoseconds_since_boot = Process.clock_gettime(CLOCK, :nanosecond)
     end
 
     def +(monotonic_time_addend)
-      @seconds_since_boot + monotonic_time_addend.seconds_since_boot
+      seconds_since_boot + monotonic_time_addend.seconds_since_boot
     end
 
     def -(monotonic_time_subtrahend)
-      @seconds_since_boot - monotonic_time_subtrahend.seconds_since_boot
+      seconds_since_boot - monotonic_time_subtrahend.seconds_since_boot
     end
 
     def to_s
-      "#{@seconds_since_boot} seconds since boot."
+      "#{seconds_since_boot} seconds since boot."
     end
 
     def to_time
-      @boot_time + @seconds_since_boot
+      @boot_time + seconds_since_boot
     end
-
   end
 end

data/lib/Monotonic/Timer.rb

@@ -5,40 +5,79 @@ require_relative './Time'
 
 module Monotonic
   class Timer
-
     class << self
+      # An interval is not an instant, and wants a different clock.  Upon Darwin
+      # CLOCK_UPTIME_RAW advances in some 42ns against the 1000ns of
+      # CLOCK_MONOTONIC, and holds while the machine sleeps, which is the right
+      # answer for a timed block: a closed lid is not execution.  Linux has no
+      # such clock, but its CLOCK_MONOTONIC already holds while suspended and
+      # advances finely, so the fallback carries the same meaning and not merely
+      # the same name.
+      #
+      # Which clocks exist is the platform's business, so this is asked rather
+      # than declared, as .resolution is.
+      def clock_name
+        @clock_name ||= %i[CLOCK_UPTIME_RAW CLOCK_MONOTONIC].find{|name| Process.const_defined?(name)}
+      end
 
       def time(&block)
         timer = Timer.new
         timer.time(&block)
       end
 
+      # How finely this clock advances, in nanoseconds.  Asked of the platform
+      # rather than claimed by the library, and worth asking: a reading is
+      # denominated in nanoseconds whether the clock affords them or not.
+      def resolution
+        Process.clock_getres(CLOCK, :nanosecond)
+      end
     end # class << self
 
+    # Read twice upon every measurement, against a floor of some tens of
+    # nanoseconds, so this is the one place here where a constant is worth the
+    # rigidity: a method call would be a measurable part of what it measures.
+    # It follows .clock_name, and so must come after it.
+    CLOCK = Process.const_get(clock_name)
+
     def start
-      @finish_time = nil
-      @start_time = Monotonic::Time.now
+      @finish_nanoseconds = nil
+      @start_nanoseconds = now
     end
 
     def stop
-      @finish_time = Monotonic::Time.now
+      @finish_nanoseconds = now
+    end
+
+    # Two exact integers differenced, which spends none of the reading.  A pair
+    # of Floats would not begin to lose the clock at this resolution until some
+    # six years of uptime, but they would begin.
+    def total_nanoseconds
+      finish_nanoseconds - @start_nanoseconds
     end
 
     def total_time
-      if @finish_time
-        @finish_time - @start_time
-      else
-        Monotonic::Time.now - @start_time
-      end
+      total_nanoseconds / NANOSECONDS_PER_SECOND.to_f
     end
 
     def time
       start
-      yield self
-    ensure
-      stop
-      return total_time
+      begin
+        yield self
+      ensure
+        stop
+      end
+      total_time
+    end
+
+    private
+
+    # A timer which has not been stopped is still running, so the finish is now.
+    def finish_nanoseconds
+      @finish_nanoseconds || now
     end
 
+    def now
+      Process.clock_gettime(CLOCK, :nanosecond)
+    end
   end
 end

data/lib/Monotonic/VERSION.rb

@@ -2,5 +2,5 @@
 # Monotonic::VERSION
 
 module Monotonic
-  VERSION = '0.6.6'
+  VERSION = '0.7.0'
 end

data/monotonic.rb.gemspec

@@ -0,0 +1,47 @@
+require_relative './lib/Monotonic/VERSION'
+
+class Gem::Specification
+  def dependencies=(gems)
+    gems.each{|gem| add_dependency(*gem)}
+  end
+
+  def development_dependencies=(gems)
+    gems.each{|gem| add_development_dependency(*gem)}
+  end
+end
+
+Gem::Specification.new do |spec|
+  spec.name = 'monotonic.rb'
+  spec.version = Monotonic::VERSION
+
+  spec.summary = "Monotonic timing made easy."
+  spec.description = "Create accurate timings of excution in Ruby."
+
+  spec.author = 'thoran'
+  spec.email = 'code@thoran.com'
+  spec.homepage = 'https://github.com/thoran/monotonic.rb'
+  spec.license = 'MIT'
+
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 2.5'
+
+  spec.files = [
+    'CHANGELOG',
+    'Gemfile',
+    Dir['lib/**/*.rb'],
+    'monotonic.rb.gemspec',
+    'Rakefile',
+    'README.md',
+    Dir['test/**/*.rb'],
+  ].flatten
+
+  spec.dependencies = %w{
+    sys-uptime
+  }
+
+  spec.development_dependencies = %w{
+    minitest
+    minitest-spec-context
+    rake
+  }
+end

data/test/Monotonic/Time_test.rb

@@ -0,0 +1,81 @@
+require_relative '../../lib/Monotonic/Time'
+
+require 'minitest/autorun'
+require 'minitest-spec-context'
+
+describe Monotonic::Time do
+  subject{Monotonic::Time.now}
+
+  describe "#initialize" do
+    it "the time spent in the block is returned as the value of the block" do
+      expect(subject.instance_variable_get(:@boot_time)) \
+        .must_equal(Sys::Uptime.boot_time)
+    end
+
+    it "the reading is taken from the monotonic clock in nanoseconds" do
+      expect((subject.instance_variable_get(:@nanoseconds_since_boot) / 1_000_000_000.0).round(2)) \
+        .must_equal((Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) / 1_000_000_000.0).round(2))
+    end
+  end
+
+  describe ".clock_name" do
+    it "is the clock which tracks time since boot as the wall clock understands it" do
+      expect(Monotonic::Time.clock_name).must_equal(:CLOCK_MONOTONIC)
+    end
+
+    it "names the clock which is read" do
+      expect(Monotonic::Time::CLOCK).must_equal(Process.const_get(Monotonic::Time.clock_name))
+    end
+  end
+
+  describe ".resolution" do
+    it "returns how finely the clock advances, in nanoseconds" do
+      expect(Monotonic::Time.resolution) \
+        .must_equal(Process.clock_getres(Process::CLOCK_MONOTONIC, :nanosecond))
+    end
+
+    it "returns an instance of integer" do
+      expect(Monotonic::Time.resolution.class).must_equal(Integer)
+    end
+  end
+
+  describe "#nanoseconds_since_boot" do
+    it "returns an instance of integer" do
+      expect((subject.nanoseconds_since_boot).class).must_equal(Integer)
+    end
+  end
+
+  describe "#seconds_since_boot" do
+    it "returns an instance of float" do
+      expect((subject.seconds_since_boot).class).must_equal(Float)
+    end
+
+    it "is the nanoseconds reading expressed in seconds" do
+      expect(subject.seconds_since_boot).must_equal(subject.nanoseconds_since_boot / 1_000_000_000.0)
+    end
+  end
+
+  describe "#+" do
+    it "returns an instance of string" do
+      expect((subject + Monotonic::Time.now).class).must_equal(Float)
+    end
+  end
+
+  describe "#-" do
+    it "returns an instance of time" do
+      expect((subject - Monotonic::Time.now).class).must_equal(Float)
+    end
+  end
+
+  describe "#to_s" do
+    it "returns an instance of string" do
+      expect(subject.to_s.class).must_equal(String)
+    end
+  end
+
+  describe "#to_time" do
+    it "returns an instance of time" do
+      expect(subject.to_time.class).must_equal(Time)
+    end
+  end
+end

data/test/Monotonic/Timer_test.rb

@@ -0,0 +1,159 @@
+require_relative '../../lib/Monotonic/Timer'
+
+require 'minitest/autorun'
+require 'minitest-spec-context'
+
+describe Monotonic::Timer do
+  context "with a block" do
+    it "the time spent in the block is returned as the value of the block" do
+      block_time = Monotonic::Timer.time do |timer|
+        sleep 3
+      end
+      expect(block_time.round).must_equal(3)
+    end
+
+    # Test introduced in 0.6.5 to demonstrate that the bug had been fixed.
+    it "the time spent in the block is returned as the value of the block and not a value at the end of the block" do
+      block_time = Monotonic::Timer.time do |timer|
+        sleep 3
+        4
+      end
+      expect(block_time.round).must_equal(3)
+    end
+
+    # Test introduced in 0.6.7 to demonstrate that the bug had been fixed.
+    it "an exception raised within the block is not swallowed" do
+      expect{Monotonic::Timer.time{raise(ArgumentError)}}.must_raise(ArgumentError)
+    end
+
+    it "allows the timer to be started and stopped within the block" do
+      Monotonic::Timer.time do |timer|
+        sleep 1
+        expect(timer.total_time.round).must_equal(1)
+        timer.stop
+        expect(timer.total_time.round).must_equal(1)
+        timer.start
+        expect(timer.total_time.round).must_equal(0)
+        sleep 1
+        expect(timer.total_time.round).must_equal(1)
+        sleep 1
+        expect(timer.total_time.round).must_equal(2)
+        timer.start
+        expect(timer.total_time.round).must_equal(0)
+      end
+    end
+
+    it "alters the block time if it is started and stopped within the block" do
+      block_time = Monotonic::Timer.time do |timer|
+        sleep 1
+        timer.stop
+        sleep 1
+        timer.start
+        sleep 1
+      end
+      expect(block_time.round).must_equal(1)
+    end
+  end
+
+  context "without a block" do
+    it 'works' do
+      timer = Monotonic::Timer.new
+      timer.start
+      sleep 1
+      expect(timer.total_time.round).must_equal(1)
+      timer.stop
+      expect(timer.total_time.round).must_equal(1)
+      timer.start
+      expect(timer.total_time.round).must_equal(0)
+      sleep 1
+      expect(timer.total_time.round).must_equal(1)
+      sleep 1
+      expect(timer.total_time.round).must_equal(2)
+      timer.start
+      expect(timer.total_time.round).must_equal(0)
+    end
+  end
+
+  context "with a block on an timer instance" do
+    it 'works' do
+      timer = Monotonic::Timer.new
+      time = timer.time do |timer|
+        sleep 1
+        expect(timer.total_time.round).must_equal(1)
+        timer.stop
+        expect(timer.total_time.round).must_equal(1)
+        sleep 1
+        expect(timer.total_time.round).must_equal(1)
+        timer.start
+        expect(timer.total_time.round).must_equal(0)
+        sleep 1
+      end
+      expect(time.round).must_equal(1)
+      expect(timer.total_time.round).must_equal(1)
+    end
+
+    # Test introduced in 0.6.7 to demonstrate that the time up to an
+    # interruption is not left running.
+    it "the time up to an interruption remains available from the timer" do
+      timer = Monotonic::Timer.new
+      begin
+        timer.time do
+          sleep 1
+          raise(ArgumentError)
+        end
+      rescue ArgumentError
+      end
+      sleep 1
+      expect(timer.total_time.round).must_equal(1)
+    end
+  end
+
+  context "the clock" do
+    it "is the finest available which holds while the machine sleeps" do
+      expect(Monotonic::Timer.clock_name) \
+        .must_equal(Process.const_defined?(:CLOCK_UPTIME_RAW) ? :CLOCK_UPTIME_RAW : :CLOCK_MONOTONIC)
+    end
+
+    it "is asked of the platform rather than declared" do
+      expect(Monotonic::Timer::CLOCK).must_equal(Process.const_get(Monotonic::Timer.clock_name))
+    end
+
+    it "reports its resolution rather than leaving it to be assumed" do
+      expect(Monotonic::Timer.resolution) \
+        .must_equal(Process.clock_getres(Monotonic::Timer::CLOCK, :nanosecond))
+    end
+
+    it "is no coarser than the one Monotonic::Time reads" do
+      expect(Monotonic::Timer.resolution).must_be :<=, Monotonic::Time.resolution
+    end
+  end
+
+  context "in nanoseconds" do
+    it "returns an instance of integer" do
+      timer = Monotonic::Timer.new
+      timer.start
+      sleep 1
+      timer.stop
+      expect(timer.total_nanoseconds.class).must_equal(Integer)
+    end
+
+    it "is the total time expressed in nanoseconds" do
+      timer = Monotonic::Timer.new
+      timer.start
+      sleep 1
+      timer.stop
+      expect(timer.total_nanoseconds / 1_000_000_000.0).must_equal(timer.total_time)
+    end
+
+    it "holds while the timer is stopped and runs on while it is not" do
+      timer = Monotonic::Timer.new
+      timer.start
+      timer.stop
+      held = timer.total_nanoseconds
+      sleep 1
+      expect(timer.total_nanoseconds).must_equal(held)
+      timer.start
+      expect(timer.total_nanoseconds).must_be :>, 0
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monotonic.rb
 version: !ruby/object:Gem::Version
-  version: 0.6.6
+  version: 0.7.0
 platform: ruby
 authors:
 - thoran
@@ -51,19 +51,40 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Create accurate timings of excution in Ruby.
 email: code@thoran.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG
+- Gemfile
+- README.md
+- Rakefile
 - lib/Monotonic/Time.rb
 - lib/Monotonic/Timer.rb
 - lib/Monotonic/VERSION.rb
 - lib/monotonic.rb
+- monotonic.rb.gemspec
+- test/Monotonic/Time_test.rb
+- test/Monotonic/Timer_test.rb
 homepage: https://github.com/thoran/monotonic.rb
 licenses:
-- Ruby
+- MIT
 metadata: {}
 rdoc_options: []
 require_paths:
@@ -79,7 +100,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Monotonic timing made easy.
 test_files: []