monotonic.rb 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 735b3915ec7e7b95ef1fde8effe2d2723fea5eb027f9af87d1bea9dc8552048a
-  data.tar.gz: 8497225d7afb17a9e6c5f1c6a7c79510986fc74f731c81c06c4b0529ca1fa1d1
+  metadata.gz: 02f12d8ccd007cc410e5ebeb524fd6761088aebe771409a81323fd331e479e61
+  data.tar.gz: 9bfd7ff12760b554b0921e535803c4e3e07c0c0cdb166b8133f1ab710a6a1d10
 SHA512:
-  metadata.gz: a9a637b1664afe2b51d8b2f6abedace3e2dd6faf150d5767da5a6add304acba0554db879f72f16867856219eee41da3ed1042418e832a76722928dea62e27511
-  data.tar.gz: fed34f80416fa88c2b31fce83a9f21576a62d678c74ca0202bedf550149842de31cd121e55cec8f377f1354b4748cd4f818333b9aed726d778310630f9c8854b
+  metadata.gz: fb3b665160980c7d6319db88518e9bd6f74a5e7eade1035a61e62c6aaa88e06110b382f02900f4e61fc7509cb7d9167084d5650c95858912c4a5b5bb2ffdcd43
+  data.tar.gz: 9c7c70bb79a05df1608516272583870cd7aab4229e13dce3d626b38fd3426a58c3529bfe2e8ddd2607f3995508c3c1cdcda287212002349db0fabea114a373b5

data/CHANGELOG

@@ -1,5 +1,25 @@
 # CHANGELOG
 
+## 20260816
+
+0.9.0: Use measurand gem, + Monotonic::Measurement and Monotonic::Timer.floor.
+
+1. + measurand as a dependency, constrained to >= 0.1.0 where Measurand#place became public. How well a figure is known is its business, and it was being hand-rolled here: combining an absolute floor with a relative drift by addition gave 109.49ns where the correct combination in quadrature gives 87.78ns, a quarter out.
+2. + Monotonic::Timer.floor: what it costs to measure at all, in nanoseconds, measured by timing measurements of nothing and remembered. The clock's tick is not the limit, an interval wanting two readings and the taking of them taking time. A high percentile rather than a median, so that the ordinary case is covered and not merely the best one. It is a floor and not an error bar: the tail is unbounded and one-sided, the scheduler being free to take the processor away between the two readings, and no single measurement can detect that it did.
+3. + Monotonic::Measurement: an elapsed interval together with what it is worth. #to_s shows only as many digits as the uncertainty reaches, the least significant place being settled by Measurand#place upon the Particle Data Group convention, so 1265625ns against a floor of 84ns prints as 1.26562ms and the same count measured coarsely prints as 1.27ms. The unit ladder is powers of a thousand and stops at seconds, the scheme being a decimal-places one and minutes being sexagesimal. Nothing is capped, a day resolved to a hundred nanoseconds printing every figure it has: the absurdity is the mismatch between instrument and question, and is better seen than rounded away.
+4. + Monotonic::Measurement#uncertainty, #measurand, #unit_name, #decimals, #nanoseconds, #floor, #drift: every figure the rendering rests upon, so that a string can be walked back to the clock which produced it.
+5. + Monotonic::Measurement#floor takes a number or anything answering to #call, and Monotonic::Timer hands over its .floor method rather than its value. Measuring the floor is a thousand null measurements, and a caller which only wants a number should not set them going: a timed block costs 0.008ms where it would cost 0.307ms, the floor being measured when doubt is first asked about.
+6. + Monotonic::Measurement drift, optional and nil by default: the relative term, being the rate at which the clock's own oscillator wanders. It cannot be measured from within, weighing a clock wanting a better clock and this being the best one here, so it is supplied by a caller or not at all.
+7. + Monotonic::Measurement#to_i and #to_f, both in nanoseconds, its own unit, as Duration::Minutes answers 5 rather than 300; #to_duration for every other unit; and #<=> with Comparable, against another measurement only, a bare number having no unit to compare against.
+8. ~ BREAKING: Monotonic::Timer#time and .time return a Monotonic::Measurement rather than a Float of seconds. What comes back now says how much of itself is real, which a bare Float could not: 0.001295791 shows nine figures upon an instrument which resolves five. #total_time and #total_nanoseconds are unchanged for a number.
+9. + Monotonic::Timer#measurement and #to_s.
+10. + test/Monotonic/Measurement_test.rb: the unit chosen, the digits allowed, the uncertainty and that it combines in quadrature, the comparison, the conversions, the lazy floor, and that every figure the rendering rests upon is reachable.
+11. + test/Monotonic/Timer_test.rb: the floor, and that a timed block returns a measurement which carries the interval and the floor.
+12. ~ test/gemspec_test.rb: the runtime dependency list.
+13. ~ README.md: + the floor and the measurement, and what a timed block now hands back.
+14. ~ Monotonic::VERSION: /0.8.0/0.9.0/
+
+
 ## 20260816
 
 0.8.0: Use duration.rb gem.

data/README.md

@@ -35,6 +35,22 @@ timer.total_nanoseconds
 # => 2508000, upon a clock which ticks in whole microseconds
 ```
 
+A timed block hands back a `Monotonic::Measurement` rather than a bare number, so that what comes back says how much of itself is real. `Monotonic::Timer.floor` is what it costs to measure at all, taken by timing measurements of nothing, and the measurement shows only as many digits as that floor reaches — the doubt itself being [measurand](https://github.com/thoran/measurand)'s business, which combines an absolute floor with a relative drift in quadrature rather than by addition.
+
+```ruby
+Monotonic::Timer.floor
+# => 84
+measurement = Monotonic::Timer.time{sleep 0.001}
+measurement.to_s
+# => "1.26562 ms"
+measurement.uncertainty
+# => 84.0
+measurement.to_duration.to_microseconds.to_f
+# => 1265.625
+```
+
+Nothing is capped: a day resolved to a hundred nanoseconds prints every figure it has, the absurdity being the mismatch between what the instrument resolves and what was asked of it, which is better seen than rounded away. The floor is a floor and not an error bar — the tail is unbounded and one-sided, the scheduler being free to take the processor away between the two readings — so repeat and take a robust statistic where that matters.
+
 
 ## Installation
 
@@ -115,26 +131,26 @@ timer.total_time
 ```ruby
 require 'monotonic.rb'
 
-time = Monotonic::Timer.time do
+measurement = Monotonic::Timer.time do
   i = 0
   1_000_000.times{puts i += 1}
 end
-time
-# => 6.975823000073433
+measurement.to_s
+# => "6.97582 s"
 ```
 
 ### Monotonic::Timer with a block and block variable
 
 ```ruby
 require 'monotonic.rb'
-time = Monotonic::Timer.time do |timer|
+measurement = 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
+measurement.to_s
+# => "6.97582 s"
 ```
 
 ### Monotonic::Timer with a block on a timer instance
@@ -142,12 +158,12 @@ time
 ```ruby
 require 'monotonic.rb'
 timer = Monotonic::Timer.new
-time = timer.time do
+measurement = timer.time do
   i = 0
   1_000_000.times{puts i += 1}
 end
-time
-# => 7.033131000120193
+measurement.to_s
+# => "7.03313 s"
 ```
 
 

data/lib/Monotonic/Measurement.rb

@@ -0,0 +1,118 @@
+# Monotonic/Measurement.rb
+# Monotonic::Measurement
+
+require 'duration.rb'
+require 'measurand'
+
+module Monotonic
+  # An elapsed interval together with what it is worth.  The count alone says
+  # nothing of how much of itself is real, so #to_s shows only as many digits as
+  # the uncertainty supports.  Nothing is capped: a day resolved to a hundred
+  # nanoseconds prints every figure it has, which looks absurd and is — the
+  # absurdity being the mismatch between what the instrument resolves and what
+  # was asked of it, and better seen than rounded away.
+  #
+  # The doubt is a Measurand's business and the unit is a Duration's; what is
+  # left here is the ladder between them and the string at the end of it.
+  class Measurement
+    include Comparable
+
+    # Powers of a thousand, and no further.  The scheme is a decimal-places one,
+    # so minutes and hours have no place in it: 90s is plainer than 1.5min, and
+    # a run of a day reads as 86400s rather than reaching for a unit which does
+    # not divide by ten.
+    UNITS = [[1, 'ns'], [1_000, 'us'], [1_000_000, 'ms'], [1_000_000_000, 's']]
+
+    attr_reader :nanoseconds
+    attr_reader :drift
+
+    # The floor may be given as a number or as anything which answers to #call,
+    # so that measuring it can wait until somebody asks about doubt.
+    # Monotonic::Timer hands over its .floor method rather than its value, and a
+    # caller which only wants a number never sets the thousand null measurements
+    # going.
+    def floor
+      @floor = @floor.respond_to?(:call) ? @floor.call : @floor
+    end
+
+    # The floor is absolute and tells upon short intervals; drift is relative
+    # and tells upon long ones, being the rate at which the clock's own
+    # oscillator wanders.  Combining them is not addition — they are independent,
+    # so they go in quadrature — which is why the arithmetic is Measurand's and
+    # not done here.
+    def measurand
+      @measurand ||= (
+        absolute = Measurand.new(@nanoseconds, floor)
+        @drift ? absolute * Measurand.relative(1, @drift) : absolute
+      )
+    end
+
+    def uncertainty
+      measurand.uncertainty
+    end
+
+    def unit
+      @unit ||= UNITS.reverse.find{|scale, _| @nanoseconds.abs >= scale} || UNITS.first
+    end
+
+    def scale
+      unit.first
+    end
+
+    def unit_name
+      unit.last
+    end
+
+    # The least significant digit worth showing is the one the uncertainty
+    # reaches, which Measurand settles by the Particle Data Group convention and
+    # reports as #place, a power of ten.  Rendering in a coarser unit moves it
+    # along by however many tens that unit is worth.  A measurand with no
+    # uncertainty has no last real digit, and answers nil.
+    def decimals
+      @decimals ||= (
+        place = measurand.place
+        place ? [Math.log10(scale) - place, 0].max.to_i : Math.log10(scale).to_i
+      )
+    end
+
+    def to_duration
+      Duration::Nanoseconds.new(@nanoseconds)
+    end
+
+    # Both answer in nanoseconds, this measurement's own unit, as
+    # Duration::Minutes answers 5 rather than 300.  Every other unit comes from
+    # #to_duration, which names the one it is asked for.  A number handed out
+    # without its unit stated must at least always mean the same thing.
+    def to_i
+      @nanoseconds
+    end
+
+    def to_f
+      @nanoseconds.to_f
+    end
+
+    def to_s
+      format("%.#{decimals}f #{unit_name}", @nanoseconds.to_f / scale)
+    end
+
+    # Against another measurement only.  A bare number has no unit, and comparing
+    # against one would have to assume which was meant, so nil is returned and ==
+    # is false, as Duration::Common does.
+    def <=>(other)
+      return nil unless other.is_a?(Monotonic::Measurement)
+      @nanoseconds <=> other.nanoseconds
+    end
+
+    def inspect
+      "#<#{self.class} #{self} (#{measurand} ns)>"
+    end
+
+    private
+
+    def initialize(nanoseconds, floor:, drift: nil)
+      @nanoseconds = nanoseconds
+      @floor = floor
+      @drift = drift
+    end
+  end
+end

data/lib/Monotonic/Timer.rb

@@ -2,6 +2,7 @@
 # Monotonic::Timer
 
 require 'duration.rb'
+require_relative './Measurement'
 
 module Monotonic
   class Timer
@@ -20,6 +21,10 @@ module Monotonic
     # rigidity: a method call would be a measurable part of what it measures.
     CLOCK = Process.const_get(CLOCK_NAMES.find{|name| Process.const_defined?(name)})
 
+    # How many measurements of nothing .floor takes, and which of them it keeps.
+    SAMPLES = 1_000
+    PERCENTILE = 0.95
+
     class << self
       def clock_name
         @clock_name ||= CLOCK_NAMES.find{|name| Process.const_defined?(name)}
@@ -36,6 +41,24 @@ module Monotonic
       def resolution
         Process.clock_getres(CLOCK, :nanosecond)
       end
+
+      # What it costs to measure at all, in nanoseconds, measured by timing
+      # measurements of nothing.  The clock's tick is not the limit: two readings
+      # must be taken, and taking them takes time, so an interval near this
+      # figure is mostly the measuring.
+      #
+      # It is a floor and not an error bar.  The typical cost is a tick or two;
+      # the tail is unbounded and one-sided, since the scheduler may take the
+      # processor away between the two readings and no single measurement can
+      # detect that it did.  A high percentile is taken rather than a median, so
+      # that the ordinary case is covered rather than merely the best one.
+      # Repeat and take a robust statistic if the tail matters.
+      def floor
+        @floor ||= (
+          samples = SAMPLES.times.map{timer = new; timer.start; timer.stop; timer.total_nanoseconds}.sort
+          samples[(samples.length * PERCENTILE).to_i]
+        )
+      end
     end # class << self
 
     # Where the instants come from.  Nothing supplied means the clock is read
@@ -87,6 +110,22 @@ module Monotonic
       to_duration.to_seconds.to_f
     end
 
+    # The elapsed interval together with what it is worth.  Not memoized: a timer
+    # which has not been stopped is still running, and so is its measurement.
+    # The floor is handed over as a method rather than a figure, so that a caller
+    # which only ever wants a number never sets the thousand null measurements
+    # going.
+    def measurement(drift: nil)
+      Monotonic::Measurement.new(total_nanoseconds, floor: self.class.method(:floor), drift: drift)
+    end
+
+    def to_s
+      measurement.to_s
+    end
+
+    # A Monotonic::Measurement rather than a bare Float, so that what comes back
+    # says how much of itself is real.  #total_time and #total_nanoseconds are
+    # still there for a number.
     def time
       start
       begin
@@ -94,7 +133,7 @@ module Monotonic
       ensure
         stop
       end
-      total_time
+      measurement
     end
 
     private

data/lib/Monotonic/VERSION.rb

@@ -2,5 +2,5 @@
 # Monotonic::VERSION
 
 module Monotonic
-  VERSION = '0.8.0'
+  VERSION = '0.9.0'
 end

data/monotonic.rb.gemspec

@@ -37,6 +37,7 @@ Gem::Specification.new do |spec|
 
   spec.dependencies = [
     ['duration.rb', '>= 0.4.0'],
+    ['measurand', '>= 0.1.0'],
     'sys-uptime'
   ]
 

data/test/Monotonic/Measurement_test.rb

@@ -0,0 +1,118 @@
+require_relative '../../lib/monotonic.rb'
+
+require 'minitest/autorun'
+require 'minitest-spec-context'
+
+describe Monotonic::Measurement do
+  def measurement(nanoseconds, floor: 84, drift: nil)
+    Monotonic::Measurement.new(nanoseconds, floor: floor, drift: drift)
+  end
+
+  describe "the unit" do
+    it "is the largest which leaves a mantissa of at least one" do
+      _(measurement(999).unit_name).must_equal('ns')
+      _(measurement(1_000).unit_name).must_equal('us')
+      _(measurement(1_265_625).unit_name).must_equal('ms')
+      _(measurement(1_000_000_000).unit_name).must_equal('s')
+    end
+
+    it "stops at seconds, the ladder being powers of a thousand" do
+      _(measurement(86_400_000_000_000).unit_name).must_equal('s')
+    end
+
+    it "is nanoseconds for nothing at all" do
+      _(measurement(0).to_s).must_equal('0 ns')
+    end
+  end
+
+  describe "the digits" do
+    it "reach as far as the uncertainty does and no further" do
+      _(measurement(1_265_625).to_s).must_equal('1.26562 ms')
+    end
+
+    it "are fewer upon a coarser instrument" do
+      _(measurement(1_265_625, floor: 100_000).to_s).must_equal('1.27 ms')
+    end
+
+    it "are none where the interval is near the floor" do
+      _(measurement(999).to_s).must_equal('999 ns')
+    end
+
+    it "are not capped, a day resolved to a hundred nanoseconds saying so" do
+      _(measurement(86_400_000_000_000).to_s).must_equal('86400.00000000 s')
+    end
+  end
+
+  describe "the uncertainty" do
+    it "is the floor alone when no drift is supplied" do
+      _(measurement(1_000_000).uncertainty).must_equal(84)
+    end
+
+    it "combines a drift in quadrature rather than by addition" do
+      combined = measurement(1_000_000_000, drift: 1e-6).uncertainty
+      _(combined).must_be_close_to(Math.sqrt(84**2 + 1_000**2), 0.01)
+      _(combined).wont_be_close_to(84 + 1_000, 1)
+    end
+
+    it "takes digits away as it grows" do
+      _(measurement(7_166_559_999, drift: 20e-6).decimals) \
+        .must_be(:<, measurement(7_166_559_999).decimals)
+    end
+
+    it "comes from a Measurand, which owns the arithmetic" do
+      _(measurement(1_000_000).measurand).must_be_instance_of(Measurand)
+    end
+  end
+
+  describe "the floor" do
+    it "may be a number" do
+      _(measurement(1_000_000, floor: 84).floor).must_equal(84)
+    end
+
+    it "may be something callable, and is not called until doubt is asked about" do
+      called = false
+      subject = Monotonic::Measurement.new(1_000_000, floor: ->{called = true; 84})
+      subject.to_i
+      subject.to_duration
+      _(called).must_equal(false)
+      subject.uncertainty
+      _(called).must_equal(true)
+      _(subject.floor).must_equal(84)
+    end
+  end
+
+  describe "comparison" do
+    it "orders one measurement against another" do
+      _(measurement(999)).must_be(:<, measurement(1_000))
+      _([measurement(1_000), measurement(999)].sort.map(&:nanoseconds)).must_equal([999, 1_000])
+    end
+
+    it "is nil against a bare number, which has no unit" do
+      _(measurement(999) <=> 999).must_be_nil
+    end
+
+    it "is therefore not equal to a bare number" do
+      _(measurement(999) == 999).must_equal(false)
+    end
+  end
+
+  describe "#to_duration" do
+    it "hands the interval to duration.rb, whose business the units are" do
+      _(measurement(1_500_000_000).to_duration).must_be_instance_of(Duration::Nanoseconds)
+      _(measurement(1_500_000_000).to_duration.to_seconds.to_f).must_equal(1.5)
+    end
+  end
+
+  describe "#to_i and #to_f" do
+    it "both answer in nanoseconds, the measurement's own unit" do
+      _(measurement(1_274_625).to_i).must_equal(1_274_625)
+      _(measurement(1_274_625).to_f).must_equal(1_274_625.0)
+    end
+
+    it "agree with one another, and with #nanoseconds" do
+      subject = measurement(1_274_625)
+      _(subject.to_f).must_equal(subject.to_i.to_f)
+      _(subject.to_i).must_equal(subject.nanoseconds)
+    end
+  end
+end

data/test/Monotonic/Timer_test.rb

@@ -9,7 +9,7 @@ describe Monotonic::Timer do
       block_time = Monotonic::Timer.time do |timer|
         sleep 3
       end
-      expect(block_time.round).must_equal(3)
+      expect(block_time.to_duration.to_seconds.to_f.round).must_equal(3)
     end
 
     # Test introduced in 0.6.5 to demonstrate that the bug had been fixed.
@@ -18,7 +18,7 @@ describe Monotonic::Timer do
         sleep 3
         4
       end
-      expect(block_time.round).must_equal(3)
+      expect(block_time.to_duration.to_seconds.to_f.round).must_equal(3)
     end
 
     # Test introduced in 0.6.7 to demonstrate that the bug had been fixed.
@@ -51,7 +51,7 @@ describe Monotonic::Timer do
         timer.start
         sleep 1
       end
-      expect(block_time.round).must_equal(1)
+      expect(block_time.to_duration.to_seconds.to_f.round).must_equal(1)
     end
   end
 
@@ -88,7 +88,7 @@ describe Monotonic::Timer do
         expect(timer.total_time.round).must_equal(0)
         sleep 1
       end
-      expect(time.round).must_equal(1)
+      expect(time.to_duration.to_seconds.to_f.round).must_equal(1)
       expect(timer.total_time.round).must_equal(1)
     end
 

data/test/gemspec_test.rb

@@ -19,7 +19,7 @@ describe 'monotonic.rb.gemspec' do
   end
 
   it "declares its runtime dependencies" do
-    _(spec.runtime_dependencies.map(&:name).sort).must_equal(%w{duration.rb sys-uptime})
+    _(spec.runtime_dependencies.map(&:name).sort).must_equal(%w{duration.rb measurand sys-uptime})
   end
 
   it "declares its development dependencies" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monotonic.rb
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - thoran
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.4.0
+- !ruby/object:Gem::Dependency
+  name: measurand
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: sys-uptime
   requirement: !ruby/object:Gem::Requirement
@@ -89,11 +103,13 @@ files:
 - Gemfile
 - README.md
 - Rakefile
+- lib/Monotonic/Measurement.rb
 - lib/Monotonic/Time.rb
 - lib/Monotonic/Timer.rb
 - lib/Monotonic/VERSION.rb
 - lib/monotonic.rb
 - monotonic.rb.gemspec
+- test/Monotonic/Measurement_test.rb
 - test/Monotonic/Time_test.rb
 - test/Monotonic/Timer_test.rb
 - test/Monotonic/VERSION_test.rb