monotonic.rb 0.7.3 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ed52df8a021bca41cae021d5b11408c8bd6b0fc80025a46a56b688cafa4fcdc
-  data.tar.gz: c45841b92c1da76259799f4c6c55ba9a540b9b25464acd82560f30a2c10e9234
+  metadata.gz: 02f12d8ccd007cc410e5ebeb524fd6761088aebe771409a81323fd331e479e61
+  data.tar.gz: 9bfd7ff12760b554b0921e535803c4e3e07c0c0cdb166b8133f1ab710a6a1d10
 SHA512:
-  metadata.gz: 4cf743fb3e9303efe1439f0532462045525b1439523bce53cfc96f293df4da5d33a94676e1b71e995cb908b29cb8295470111dc7857d6712e569ca348a45f6f6
-  data.tar.gz: 739e6a9032050231fdc5f761a6581a70aded2512981f7cf9e34e6774a43215e87db9d3911c6aec214269ac1a08282ef5933920e2121ab11119f6b0c34f5ef0a1
+  metadata.gz: fb3b665160980c7d6319db88518e9bd6f74a5e7eade1035a61e62c6aaa88e06110b382f02900f4e61fc7509cb7d9167084d5650c95858912c4a5b5bb2ffdcd43
+  data.tar.gz: 9c7c70bb79a05df1608516272583870cd7aab4229e13dce3d626b38fd3426a58c3529bfe2e8ddd2607f3995508c3c1cdcda287212002349db0fabea114a373b5

data/CHANGELOG

@@ -1,5 +1,50 @@
 # 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.
+
+1. + duration.rb as a dependency, constrained to >= 0.4.0 where sys-uptime is unconstrained. Units and the arithmetic between them are its business, and were being hand-rolled here. 0.4.0 is where Duration::Nanoseconds arrived, which this gem names, and is the true minimum rather than a guess: the whole API used here exercises clean against it, and everything between is additive.
+2. ~ monotonic.rb.gemspec: spec.dependencies takes a name and a requirement as well as a bare name, the splat in #dependencies= already allowing for it. sys-uptime stays unconstrained as before.
+3. - Monotonic::NANOSECONDS_PER_SECOND, introduced at 0.7.0 and by now divided by in four places. It existed only because the conversion was hand-rolled; a duration converts by exact ratios and stays a Rational until to_f is asked for, where the constant dropped to Float a step early.
+4. + Monotonic::Timer#to_duration, being a Duration::Nanoseconds. An elapsed interval is a duration, and every unit follows from this one exactly.
+5. ~ Monotonic::Timer#total_time: derived from #to_duration. It returns a Float of seconds as before.
+6. ~ Monotonic::Time#seconds_since_boot: converted by a duration rather than by division. It returns a Float as before.
+7. ~ BREAKING: Monotonic::Time#- returns a Duration::Nanoseconds where it returned a Float of seconds. The difference of two instants is a duration, and that is the reason a monotonic clock is read at all. Given a duration instead it returns the earlier instant.
+8. ~ BREAKING: Monotonic::Time#+ takes a Duration and returns a later Monotonic::Time. Given another instant it raises TypeError, where it formerly returned the sum of two seconds-since-boot figures: a quantity which moves when the epoch moves is not a quantity, and the README demonstrated it producing 2417598.681896, which was nothing at all. Ruby's own Time raises upon time + time for the same reason.
+9. ~ Monotonic::Time#initialize takes an optional nanoseconds-since-boot, defaulting to the clock, so that #+ and #- can answer with an instant other than now.
+10. ~ lib/Monotonic/Timer.rb: the constants moved above the methods, CLOCK no longer following .clock_name. + Monotonic::Timer::CLOCK_NAMES, declaring what would be accepted and in what order, so that CLOCK derives from it rather than from a method and need not come after one.
+11. ~ test/Monotonic/Time_test.rb: #+ and #- rewritten for the arithmetic above, including that an instant plus an instant raises and a bare number is refused.
+12. + test/Monotonic/Timer_test.rb: #to_duration, that it carries the same figure as #total_nanoseconds and converts to the same seconds as #total_time.
+13. ~ test/gemspec_test.rb: the runtime dependency list.
+14. ~ README.md: + what belongs to duration.rb and why, and the usage for the arithmetic and #to_duration.
+15. ~ Monotonic::Time#+ and #-: dispatch upon what the argument answers to rather than upon its class. One question tells the two cases apart — does this know where it sits since boot? — and it is asked of the object: an instant subtracts to a duration, and anything converting to nanoseconds shifts the instant. The refusal of instant plus instant is asked of the same duck, since leaving it to Monotonic::Time happening not to answer #to_nanoseconds would be an accident rather than a rule. A bare number still raises TypeError, the guard asking respond_to? rather than is_a?: duck typing forbids asking after a class, not asking after a capability. Ruby raises TypeError for an unsuitable operand throughout — Time, Integer, Float, Rational — and NoMethodError is a NameError, the family meaning that something named does not exist, where here the caller named #- which does. The message carries the protocol a duck must satisfy, so nothing is lost by not letting it escape. The parameters are named for their arithmetic role rather than for a type: /monotonic_time_addend/addend/ and /monotonic_time_subtrahend/subtrahend/, the type half of each having been an unenforced claim in any case, the old #- never having checked what it was given.
+16. + Monotonic::Timer#initialize takes instants:, defaulting to nil, which reads the clock directly as before. Supplied with Monotonic::Time it times upon CLOCK_MONOTONIC instead: coarser, at 1000ns against 42ns, but placeable against the wall clock through #to_time. Anything answering .now will do. This is what 0.7.0 took away without saying so, Timer having read Monotonic::Time as its substrate since 0.1.0 until the two took different clocks — and it could not be given back before now, Monotonic::Time#- having answered with a bare Float of seconds until this release, so that an interval taken from it would have been reported as nanoseconds and been wrong by a factor of a billion.
+17. ~ Monotonic::Timer#total_nanoseconds asks the elapsed figure to say itself in nanoseconds where it can, a raw difference already being in them and an instant's difference being a duration.
+18. + test/Monotonic/Timer_test.rb: which source is read, that either answers in nanoseconds, and that a supplied source times upon its own clock, the figure falling upon a multiple of that clock's resolution.
+19. ~ Monotonic::VERSION: /0.7.3/0.8.0/
+
+
 ## 20260816
 
 0.7.3: Require Monotonic::Time from the gem, and stop every instant fetching the boot time.
@@ -13,7 +58,6 @@
 7. + .gitignore: the standard list, as duration.rb and namo carry verbatim, in place of the three lines here. It is not among spec.files, so nothing in the published gem changes by it.
 8. ~ Monotonic::VERSION: /0.7.2/0.7.3/
 
-
 ## 20260812
 
 0.7.2: + gemspec test.

data/README.md

@@ -14,35 +14,62 @@ Which clock is read follows from that. `Monotonic::Timer` measures intervals and
 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
+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.
+A reading is denominated in nanoseconds whether or not the clock affords it, 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.
+
+Units and the arithmetic between them belong to [duration.rb](https://github.com/thoran/duration.rb), which this gem depends upon rather than reimplementing. An elapsed interval is a duration, so `Monotonic::Timer#to_duration` hands one back and every unit follows from it exactly, a Rational until `to_f` is asked for. An instant is not a duration: `Monotonic::Time#-` gives the duration between two instants, `#+` takes a duration and gives a later instant, and adding one instant to another raises — a quantity which moves when you move the epoch is not a quantity, and Ruby's own `Time` refuses it for the same reason.
 
 What `Monotonic::Time` is for follows from that. It is the point type: `Monotonic::Timer` used it as its own substrate until 0.7.0, when the two took different clocks, and what remains to it is what a point is good for — the difference of two instants, which is the reason a monotonic clock is read at all, and `#to_time`, which places one against the wall clock by way of the boot time.
 
+Where a timing is taken from can be chosen. `Monotonic::Timer.new` reads the clock directly, as it always has and much the cheapest; `Monotonic::Timer.new(instants: Monotonic::Time)` times upon `CLOCK_MONOTONIC` instead, coarser but placeable against the wall clock. Anything answering `.now` will do.
+
+```ruby
+timer = Monotonic::Timer.new(instants: Monotonic::Time)
+timer.start; sleep 0.002; timer.stop
+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
 
 Add this line to your application's Gemfile:
 
 ```ruby
-  gem 'monotonic.rb'
+gem 'monotonic.rb'
 ```
 
 And then execute:
 
 ```bash
-  $ bundle install
+$ bundle install
 ```
 
 Or install it yourself as:
 
 ```bash
-  $ gem install monotonic.rb
+$ gem install monotonic.rb
 ```
 
 
@@ -51,74 +78,92 @@ Or install it yourself as:
 ### 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
+require 'monotonic.rb'
+
+monotonic_time = Monotonic::Time.new
+monotonic_time.nanoseconds_since_boot
+# => 2614365376498000
+
+monotonic_time.seconds_since_boot
+# => 1208799.325906
+
+monotonic_time + Duration::Seconds.new(30)
+# => #<Monotonic::Time>, thirty seconds later
+
+Monotonic::Time.now - monotonic_time
+# => #<Duration::Nanoseconds @nanoseconds=44104999>
+
+monotonic_time + Monotonic::Time.now
+# => TypeError: an instant plus an instant is not an instant
+
+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
+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.to_duration
+# => #<Duration::Nanoseconds @nanoseconds=27734000>
+
+timer.to_duration.to_microseconds.to_f
+# => 27734.0
+
+timer.total_time
+# => 0.027734
 ```
 
 ### 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
+require 'monotonic.rb'
+
+measurement = Monotonic::Timer.time do
+  i = 0
+  1_000_000.times{puts i += 1}
+end
+measurement.to_s
+# => "6.97582 s"
 ```
 
 ### 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
+require 'monotonic.rb'
+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
+measurement.to_s
+# => "6.97582 s"
 ```
 
 ### 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
+require 'monotonic.rb'
+timer = Monotonic::Timer.new
+measurement = timer.time do
+  i = 0
+  1_000_000.times{puts i += 1}
+end
+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/Time.rb

@@ -1,22 +1,23 @@
 # Monotonic/Time.rb
 # Monotonic::Time
 
+require 'duration.rb'
 require 'sys-uptime'
 
 module Monotonic
-  NANOSECONDS_PER_SECOND = 1_000_000_000
-
   class Time
+    # 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.  .clock_name is a method
+    # all the same, so that the two classes answer the question alike.
+    CLOCK = Process::CLOCK_MONOTONIC
+
     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
@@ -25,27 +26,14 @@ module Monotonic
         self.new
       end
 
-      # Invariant for the life of the process, coming from kern.boottime, which
-      # does not move.  It was asked afresh upon every instance and cost 1740ns
-      # of the 1947ns an instant took to make.
-      def boot_time
-        @boot_time ||= Sys::Uptime.boot_time
-      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
 
-    # 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,
@@ -53,19 +41,45 @@ module Monotonic
     # 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
+      Duration::Nanoseconds.new(@nanoseconds_since_boot).to_seconds.to_f
     end
 
-    def initialize
-      @nanoseconds_since_boot = Process.clock_gettime(CLOCK, :nanosecond)
+    def initialize(nanoseconds_since_boot = Process.clock_gettime(CLOCK, :nanosecond))
+      @nanoseconds_since_boot = nanoseconds_since_boot
     end
 
-    def +(monotonic_time_addend)
-      seconds_since_boot + monotonic_time_addend.seconds_since_boot
+    # One question tells the two cases apart, and it is asked of the object
+    # rather than of its class: does this know where it sits since boot?  If it
+    # does it is an instant, and if it converts to nanoseconds it is a duration.
+    # Nothing here names a class, so anything answering the same messages will
+    # do.
+    #
+    # An instant plus a duration is an instant.  An instant plus an instant is
+    # nothing at all: it depends upon where the epoch was arbitrarily put, and a
+    # quantity which moves when you move the origin is not a quantity.  Ruby's
+    # own Time refuses it, with "time + time?", and so does this.  The refusal is
+    # asked of the duck too, since leaving it to Monotonic::Time happening not to
+    # answer #to_nanoseconds would be an accident rather than a rule.
+    def +(addend)
+      if addend.respond_to?(:nanoseconds_since_boot)
+        raise TypeError, "can't add #{addend.class} to #{self.class}: an instant plus an instant is not an instant"
+      end
+      unless addend.respond_to?(:to_nanoseconds)
+        raise TypeError, "can't add #{addend.class} to #{self.class}: expected something answering to #to_nanoseconds"
+      end
+      self.class.new(@nanoseconds_since_boot + addend.to_nanoseconds.to_i)
     end
 
-    def -(monotonic_time_subtrahend)
-      seconds_since_boot - monotonic_time_subtrahend.seconds_since_boot
+    # Minus an instant it is the duration between them; minus a duration it is
+    # the earlier instant.  The first is why a monotonic clock is read at all.
+    def -(subtrahend)
+      if subtrahend.respond_to?(:nanoseconds_since_boot)
+        Duration::Nanoseconds.new(@nanoseconds_since_boot - subtrahend.nanoseconds_since_boot)
+      elsif subtrahend.respond_to?(:to_nanoseconds)
+        self.class.new(@nanoseconds_since_boot - subtrahend.to_nanoseconds.to_i)
+      else
+        raise TypeError, "can't subtract #{subtrahend.class} from #{self.class}: expected an instant, or something answering to #to_nanoseconds"
+      end
     end
 
     def to_s

data/lib/Monotonic/Timer.rb

@@ -1,23 +1,33 @@
 # Monotonic/Timer.rb
 # Monotonic::Timer
 
-require_relative './Time'
+require 'duration.rb'
+require_relative './Measurement'
 
 module Monotonic
   class Timer
+    # 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.  This is what would be accepted, in order; which of them exists is
+    # the platform's business, and .clock_name reports what was found.
+    CLOCK_NAMES = %i[CLOCK_UPTIME_RAW CLOCK_MONOTONIC]
+
+    # 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.
+    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
-      # 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)}
+        @clock_name ||= CLOCK_NAMES.find{|name| Process.const_defined?(name)}
       end
 
       def time(&block)
@@ -31,13 +41,40 @@ 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
 
-    # 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)
+    # Where the instants come from.  Nothing supplied means the clock is read
+    # directly, which is what this has always done and is much the cheapest: a
+    # raw reading costs some 57ns against the 171ns of making a Monotonic::Time,
+    # and two are taken per measurement.
+    #
+    # Supplying Monotonic::Time times upon CLOCK_MONOTONIC instead — coarser, at
+    # 1000ns against 42ns, but it maps back onto the wall clock, so a timing can
+    # be placed as well as measured.  Anything answering .now will do, its
+    # instants needing only to subtract to something which can say itself in
+    # nanoseconds.  That is what 0.7.0 took away without saying so, Timer having
+    # read Monotonic::Time until the two took different clocks.
+    def initialize(instants: nil)
+      @instants = instants
+    end
 
     def start
       @finish_nanoseconds = nil
@@ -51,14 +88,44 @@ module Monotonic
     # 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.
+    #
+    # Raw readings difference to nanoseconds already.  Instants difference to
+    # whatever their own subtraction gives, so it is asked to say itself in
+    # nanoseconds — which is why this could not be done before 0.8.0, where
+    # Monotonic::Time#- began answering with a duration rather than a bare Float
+    # of seconds.
     def total_nanoseconds
-      finish_nanoseconds - @start_nanoseconds
+      elapsed = finish_nanoseconds - @start_nanoseconds
+      elapsed.respond_to?(:to_nanoseconds) ? elapsed.to_nanoseconds.to_i : elapsed
+    end
+
+    # An elapsed interval is a duration, so here is one, and every unit follows
+    # from it exactly.  #total_time is the same figure in seconds, that being
+    # the unit this library has always answered in.
+    def to_duration
+      Duration::Nanoseconds.new(total_nanoseconds)
     end
 
     def total_time
-      total_nanoseconds / NANOSECONDS_PER_SECOND.to_f
+      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
@@ -66,7 +133,7 @@ module Monotonic
       ensure
         stop
       end
-      total_time
+      measurement
     end
 
     private
@@ -77,7 +144,7 @@ module Monotonic
     end
 
     def now
-      Process.clock_gettime(CLOCK, :nanosecond)
+      @instants ? @instants.now : Process.clock_gettime(CLOCK, :nanosecond)
     end
   end
 end

data/lib/Monotonic/VERSION.rb

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

data/monotonic.rb.gemspec

@@ -35,9 +35,11 @@ Gem::Specification.new do |spec|
     Dir['test/**/*.rb'],
   ].flatten
 
-  spec.dependencies = %w{
-    sys-uptime
-  }
+  spec.dependencies = [
+    ['duration.rb', '>= 0.4.0'],
+    ['measurand', '>= 0.1.0'],
+    'sys-uptime'
+  ]
 
   spec.development_dependencies = %w{
     minitest

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/Time_test.rb

@@ -55,14 +55,35 @@ describe Monotonic::Time do
   end
 
   describe "#+" do
-    it "returns an instance of string" do
-      expect((subject + Monotonic::Time.now).class).must_equal(Float)
+    it "returns a later instant when given a duration" do
+      expect((subject + Duration::Seconds.new(5)).class).must_equal(Monotonic::Time)
+    end
+
+    it "advances by exactly that duration" do
+      expect((subject + Duration::Seconds.new(5)).nanoseconds_since_boot - subject.nanoseconds_since_boot) \
+        .must_equal(5_000_000_000)
+    end
+
+    it "refuses another instant, there being no such quantity" do
+      expect{subject + Monotonic::Time.now}.must_raise(TypeError)
+    end
+
+    it "refuses a bare number, which has no unit" do
+      expect{subject + 5}.must_raise(TypeError)
     end
   end
 
   describe "#-" do
-    it "returns an instance of time" do
-      expect((subject - Monotonic::Time.now).class).must_equal(Float)
+    it "returns the duration between two instants" do
+      expect((subject - Monotonic::Time.now).class).must_equal(Duration::Nanoseconds)
+    end
+
+    it "returns an earlier instant when given a duration" do
+      expect((subject - Duration::Seconds.new(5)).class).must_equal(Monotonic::Time)
+    end
+
+    it "refuses a bare number, which has no unit" do
+      expect{subject - 5}.must_raise(TypeError)
     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
 
@@ -128,6 +128,57 @@ describe Monotonic::Timer do
     end
   end
 
+  context "where the instants come from" do
+    it "reads the clock directly when nothing is supplied" do
+      timer = Monotonic::Timer.new
+      timer.start
+      timer.stop
+      expect(timer.total_nanoseconds.class).must_equal(Integer)
+    end
+
+    it "takes them from whatever is supplied, in nanoseconds still" do
+      timer = Monotonic::Timer.new(instants: Monotonic::Time)
+      timer.start
+      sleep 0.01
+      timer.stop
+      expect(timer.total_nanoseconds.class).must_equal(Integer)
+      expect(timer.total_nanoseconds).must_be :>, 5_000_000
+    end
+
+    it "times upon that source's clock rather than its own" do
+      timer = Monotonic::Timer.new(instants: Monotonic::Time)
+      timer.start
+      sleep 0.01
+      timer.stop
+      expect(timer.total_nanoseconds % Monotonic::Time.resolution).must_equal(0)
+    end
+  end
+
+  context "as a duration" do
+    it "hands back a Duration::Nanoseconds" do
+      timer = Monotonic::Timer.new
+      timer.start
+      timer.stop
+      expect(timer.to_duration.class).must_equal(Duration::Nanoseconds)
+    end
+
+    it "carries the same figure as #total_nanoseconds" do
+      timer = Monotonic::Timer.new
+      timer.start
+      sleep 0.01
+      timer.stop
+      expect(timer.to_duration.to_i).must_equal(timer.total_nanoseconds)
+    end
+
+    it "converts exactly, #total_time being the same in seconds" do
+      timer = Monotonic::Timer.new
+      timer.start
+      sleep 0.01
+      timer.stop
+      expect(timer.to_duration.to_seconds.to_f).must_equal(timer.total_time)
+    end
+  end
+
   context "in nanoseconds" do
     it "returns an instance of integer" do
       timer = Monotonic::Timer.new

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{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.7.3
+  version: 0.9.0
 platform: ruby
 authors:
 - thoran
@@ -9,6 +9,34 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: duration.rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !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
@@ -75,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