monotonic.rb 0.6.7 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9992e2194aa62416707e8ee507f68f870e4eea0cbee2770879017d07d2ff7e7
-  data.tar.gz: 8221c6232e0c2f1df21d9d5faaf42c7292ed1052801c8fe7f8cd6b819fdd4bde
+  metadata.gz: 577e4ce149e58981c889c52eaed6256c4c11a5bf2d1e6144513d3cd8c0d72705
+  data.tar.gz: 60b83880903cbe10e28ab23462953ecc6b43296c1c39ae08e5c8cc6442697794
 SHA512:
-  metadata.gz: 7a827ddd7420e8ff5911ca543cc5dbf46765063f521fefb55f0be0f883fe73c21b2552f43d5e6890e6a01e826c335c8d86ddfdb8db087983f25fd029d91e3cf0
-  data.tar.gz: 35d7a1115045c486bd49074f31098a6d0c6d2e21fa795a0f07fd842120a1b3a407c9f3b76456b31dd8a185c4659212ba8bd85e08cd7968d7bd33beede84c8a19
+  metadata.gz: '084908b43a5095d6ff4a3928a6161abb5800ce113714036afdd3bbc89c361886292c603d2f44bd33014d4fa0c5f8e25779c183933e1c4336c2767991ec21b194'
+  data.tar.gz: 252ba0130e324f322c37cb4df402a307ff534580ff422fc8b7ddbda494b3e8b28d0c681417dde96989d6d8f1d4dc8f2eb6bd5c9847b167b3176295fc88f27561

data/CHANGELOG

@@ -1,5 +1,28 @@
 # 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.

data/README.md

@@ -1,24 +1,49 @@
 # 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
+  $ bundle install
 ```
+
 Or install it yourself as:
+
 ```bash
   $ gem install monotonic.rb
 ```
 
+
 ## Usage
 
 ### Monotonic::Time
@@ -26,6 +51,8 @@ Or install it yourself as:
 ```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
@@ -47,6 +74,8 @@ Or install it yourself as:
   i = 0
   1_000_000.times{puts i += 1}
   timer.stop
+  timer.total_nanoseconds
+  # => 27734000
   timer.total_time
   # => 7.166559999808669
 ```
@@ -90,6 +119,7 @@ Or install it yourself as:
   # => 7.033131000120193
 ```
 
+
 ## Contributing
 
 1. Fork it ( https://github.com/thoran/monotonic.rb/fork )

data/lib/Monotonic/Time.rb

@@ -4,34 +4,70 @@
 require 'sys-uptime'
 
 module Monotonic
+  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

@@ -6,27 +6,57 @@ 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
@@ -38,5 +68,16 @@ module Monotonic
       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.7'
+  VERSION = '0.7.0'
 end

data/test/Monotonic/Time_test.rb

@@ -12,16 +12,47 @@ describe Monotonic::Time do
         .must_equal(Sys::Uptime.boot_time)
     end
 
-    it "the time spent in the block is returned as the value of the block" do
-      expect(subject.instance_variable_get(:@seconds_since_boot).round(2)) \
-        .must_equal(Process.clock_gettime(Process::CLOCK_MONOTONIC).round(2))
+    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 string" 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

data/test/Monotonic/Timer_test.rb

@@ -107,4 +107,53 @@ describe Monotonic::Timer do
       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.7
+  version: 0.7.0
 platform: ruby
 authors:
 - thoran
@@ -100,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: []