monotime 0.5.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbb84fdd4db4d629ca5d4cc847c47d9003f4553f010b575364f7ad562c16bb4d
-  data.tar.gz: 40729463ba3970e77110c2ae92620f4d6ca08b6d9997776272a3d0a05a03b595
+  metadata.gz: 8a9395967e506d690912041251bc7b6afd1a373aa49d0b4425ec08ca611e5238
+  data.tar.gz: '09ec6a1e96c9ce434d4847d275d85f7514c4a9bb3d9c71d205b04ab0f06e6d5b'
 SHA512:
-  metadata.gz: 2916513d7d5dada28d18855d7644055cf82ddd6d2ad66ebd27c7a73d9ae2c88cde94887e7769d007372768c7acbcac32d8210308f9bc2ba2256b150126f29d9b
-  data.tar.gz: cff3a4bd7be443460f7dfc65432da3f3d30fef62433e5caa73c932497d490fdc5641b34659f18d8790bb0797449d93b9019f46678c0489b3aa9756c871222bd1
+  metadata.gz: a68a338484a8534a8953abf5bec0a98a6b7a2dc6a506cd1f5fb1e3b29e1b534fa0d41e4175aa81598273ee5d706d16caeb60ce1b89a92b5e8192f87a960265f3
+  data.tar.gz: f9f329d74339eccc1b4c50007d2cb93cc87132ce6a5841faa327d4db48dfb347df8faee3f9777551cb686e90001def65d72c8a77c6b6df4dfed1d847598ac685

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['2.5', '2.6', '2.7', '3.0', jruby, truffleruby]
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - run: bundle exec rake

data/.rubocop.yml

@@ -1,6 +1,18 @@
-Metrics/LineLength:
+AllCops:
+  NewCops: enable
+  Exclude:
+    - "bin/*"
+    - "test/*"
+    - "*.gemspec"
+    - "Rakefile"
+    - "Gemfile"
+
+Layout/LineLength:
   Max: 96
 
+Metrics/ClassLength:
+  Max: 120
+
 Style/AsciiComments:
   Enabled: false
 
@@ -9,3 +21,18 @@ Style/AccessModifierDeclarations:
 
 Style/FormatStringToken:
   Enabled: false
+
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true
+
+Style/ExplicitBlockArgument:
+  Enabled: false
+
+Style/MixinUsage:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+## 0.7.1 - 2021-10-22
+### Added
+ - `simplecov` introduced to test suite.
+ - `monotime/include.rb` to auto-include types globally.
+
+### Changed
+ - All `Instant` and `Duration` instances are now frozen.
+ - Migrate from Travis CI to Github Actions
+ - Update development dependency on `rake`.
+
+## [0.7.0] - 2019-04-24
+### Added
+ - `Duration.with_measure`, which yields and returns an array containing its
+   evaluated return value and its `Duration`.
+
+### Changed
+ - Break `Duration` and `Instant` into their own files.
+ - Rename `Monotime::VERSION` to `Monotime::MONOTIME_VERSION` to reduce
+   potential for collision if the module is included.
+ - Update to bundler 2.0.
+ - Rework README.md.  Includes fix for [issue #1] (added a "See Also" section).
+
+## [0.6.1] - 2018-10-26
+### Fixed
+ - Build gem from a clean git checkout, not my local development directory.
+   No functional changes.
+
+## [0.6.0] - 2018-10-26
+### Added
+ - This `CHANGELOG.md` by request of [@celsworth].
+ - Aliases for `Duration.from_*` and `Duration#to_*` without the prefix.  e.g.
+   `Duration.from_secs(42).to_secs == 42` can now be written as
+   `Duration.secs(42).secs == 42`.
+ - `Duration#nonzero?`.
+ - `Instant#in_past?` and `Instant#in_future?`.
+
+## [0.5.0] - 2018-10-13
+### Added
+ - `Duration#abs` to make a `Duration` positive.
+ - `Duration#-@` to invert the sign of a `Duration`.
+ - `Duration#positive?`
+ - `Duration#negative?`
+ - `Duration#zero?`
+
+### Changed
+ - `Instant#sleep` with no argument now sleeps until the `Instant`.
+ - `Duration.from_*` no longer coerce their argument to `Float`.
+ - `Duration#==` checks value via `#to_nanos`, not type.
+ - `Duration#eql?` checks value and type.
+ - `Duration#<=>` compares value via `#to_nanos`.
+
+## [0.4.0] - 2018-10-09
+### Added
+ - `Instant#sleep` - sleep to a given `Duration` past an `Instant`.
+ - `Instant#sleep_secs` and `Instant#sleep_millis` convenience methods.
+ - `Duration#sleep` - sleep for the `Duration`.
+ - `Duration#*` - multiply a `Duration` by a number.
+ - `Duration#/` - divide a `Duration` by a number.
+
+### Changed
+- More `#to_nanos` `Duration` duck-typing.
+
+## [0.3.0] - 2018-10-04
+### Added
+ - `#to_nanos` is now used to duck-type `Duration` everywhere.
+
+### Changed
+ - Make `<=>` return nil on invalid types, rather than raising a `TypeError`.
+
+### Removed
+ - Dependency on `dry-equalizer`.
+
+## [0.2.0] - 2018-10-03
+### Added
+ - `Instant#to_s` as an alias for `#elapsed.to_s`
+ - `Duration#to_nanos`, with some limited duck-typing.
+
+### Changed
+ - Switch to microseconds internally.
+ - `Duration#to_{secs,millis,micros}` now return a `Float`.
+ - `Instant#ns` is now `protected`.
+
+### Fixed
+ - `Duration#to_s` zero-stripping with precision=0.
+ - `Instant#-` argument ordering with other `Instant`.
+ - `Duration#to_micros` returns microseconds, not picoseconds.
+
+### Removed
+ - `Instant` and `Duration` maths methods no longer support passing an `Integer`
+   number of nanoseconds.
+
+## [0.1.0] - 2018-10-02
+### Added
+ - Initial release
+
+
+[0.1.0]: https://github.com/Freaky/monotime/commits/v0.1.0
+[0.2.0]: https://github.com/Freaky/monotime/commits/v0.2.0
+[0.3.0]: https://github.com/Freaky/monotime/commits/v0.3.0
+[0.4.0]: https://github.com/Freaky/monotime/commits/v0.4.0
+[0.5.0]: https://github.com/Freaky/monotime/commits/v0.5.0
+[0.6.0]: https://github.com/Freaky/monotime/commits/v0.6.0
+[0.6.1]: https://github.com/Freaky/monotime/commits/v0.6.1
+[0.7.0]: https://github.com/Freaky/monotime/commits/v0.7.0
+[issue #1]: https://github.com/Freaky/monotime/issues/1
+[@celsworth]: https://github.com/celsworth

data/README.md

@@ -1,5 +1,7 @@
 [![Gem Version](https://badge.fury.io/rb/monotime.svg)](https://badge.fury.io/rb/monotime)
-[![Build Status](https://travis-ci.org/Freaky/monotime.svg?branch=master)](https://travis-ci.org/Freaky/monotime)
+![Build Status](https://github.com/Freaky/monotime/actions/workflows/ci.yml/badge.svg)
+[![Inline docs](http://inch-ci.org/github/Freaky/monotime.svg?branch=master)](http://inch-ci.org/github/Freaky/monotime)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/gems/monotime)
 
 # Monotime
 
@@ -21,66 +23,75 @@ Or install it yourself as:
 
     $ gem install monotime
 
-## Usage
+`Monotime` is tested on Ruby 2.5—3.0 and recent JRuby 9.x releases.
 
-The typical way everyone does "correct" elapsed-time measurements in Ruby is
-this pile of nonsense:
+## Usage
 
 ```ruby
-start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-do_something
-elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+require 'monotime'
+# or, to automatically include Monotime::* in the global scope,
+# as used by these examples:
+require 'monotime/include'
 ```
 
-Not only is it long-winded, it's imprecise, converting to floating point instead
-of working off precise timestamps.
+`Monotime` offers a `Duration` type for describing spans of time, and an
+`Instant` type for describing points in time.  Both operate at nanosecond
+resolution to the limits of whatever your Ruby implementation supports.
 
-`Monotime` offers this alternative:
+For example, to measure an elapsed time, either create an `Instant` to mark the
+start point, perform the action and then ask for the `Duration` that has elapsed
+since:
 
 ```ruby
-include Monotime
-
 start = Instant.now
 do_something
 elapsed = start.elapsed
+```
 
-# or
+Or use a convenience method:
+
+```ruby
 elapsed = Duration.measure { do_something }
+# or
+return_value, elapsed = Duration.with_measure { compute_something }
 ```
 
-`elapsed` is not a dimensionless `Float`, but a `Duration` type, and internally
-both `Instant` and `Duration` operate in *nanoseconds* to most closely match
-the native timekeeping types used by most operating systems.
+`Duration` offers formatting:
+
+```ruby
+Duration.millis(42).to_s       # => "42ms"
+Duration.nanos(12345).to_s     # => "12.345μs"
+Duration.secs(1.12345).to_s(2) # => "1.12s"
+```
 
-`Duration` knows how to format itself:
+Conversions:
 
 ```ruby
-Duration.from_millis(42).to_s       # => "42ms"
-Duration.from_nanos(12345).to_s     # => "12.345μs"
-Duration.from_secs(1.12345).to_s(2) # => "1.12s"
+Duration.secs(10).millis    # => 10000.0
+Duration.micros(12345).secs # => 0.012345
 ```
 
-And how to do basic maths on itself:
+And basic mathematical operations:
 
 ```ruby
-(Duration.from_millis(42) + Duration.from_secs(1)).to_s  # => "1.042s"
-(Duration.from_millis(42) - Duration.from_secs(1)).to_s  # => "-958ms"
-(Duration.from_secs(42) * 2).to_s                        # => "84s"
-(Duration.from_secs(42) / 2).to_s                        # => "21s"
+(Duration.millis(42) + Duration.secs(1)).to_s  # => "1.042s"
+(Duration.millis(42) - Duration.secs(1)).to_s  # => "-958ms"
+(Duration.secs(42) * 2).to_s                   # => "84s"
+(Duration.secs(42) / 2).to_s                   # => "21s"
 ```
 
 `Instant` does some simple maths too:
 
 ```ruby
 # Instant - Duration => Instant
-(Instant.now - Duration.from_secs(1)).elapsed.to_s # => "1.000014627s"
+(Instant.now - Duration.secs(1)).elapsed.to_s      # => "1.000014627s"
 
 # Instant - Instant => Duration
 (Instant.now - Instant.now).to_s                   # => "-5.585μs"
 ```
 
 `Duration` and `Instant` are also `Comparable` with other instances of their
-type, and support `#hash` for use in, er, hashes.
+type, and can be used in hashes, sets, and similar structures.
 
 ## Sleeping
 
@@ -89,35 +100,38 @@ is not yet implemented):
 
 ```ruby
 # Equivalent
-sleep(Duration.from_secs(1).to_secs)  # => 1
-
-Duration.from_secs(1).sleep           # => 1
+sleep(Duration.secs(1).secs)  # => 1
+Duration.secs(1).sleep        # => 1
 ```
 
 So can `Instant`, taking a `Duration` and sleeping until the given `Duration`
-past the time the `Instant` was created, if any.  This may be useful if you wish
-to maintain an approximate interval while performing work in between:
+past the time the `Instant` was created, if any. This can be useful for
+maintaining a precise candence between tasks:
 
 ```ruby
-poke_duration = Duration.from_secs(60)
+interval = Duration.secs(60)
+start = Instant.now
 loop do
-  start = Instant.now
-  poke_my_api(api_to_poke, what_to_poke_it_with)
-  start.sleep(poke_duration) # sleeps 60 seconds minus how long poke_my_api took
-  # alternative: start.sleep_secs(60)
+  do_stuff
+  start.sleep(interval)
+  start += interval
 end
 ```
 
-Or you can declare a future `Instant` and ask to sleep until it passes:
+Or you can declare an `Instant` in the future and sleep to that point:
 
 ```ruby
-next_minute = Instant.now + Duration.from_secs(60)
-do_stuff
-next_minute.sleep # => sleeps any remaining seconds
+interval = Duration.secs(60)
+deadline = Instant.now + interval
+loop do
+  do_stuff
+  deadline.sleep
+  deadline += interval
+end
 ```
 
-`Instant#sleep` returns a `Duration` which was slept, or a negative `Duration` if
-the desired sleep period has passed.
+`Instant#sleep` returns a `Duration` which was slept, or a negative `Duration`
+indicating that the desired sleep point was in the past.
 
 ## Duration duck typing
 
@@ -133,8 +147,8 @@ class Numeric
   end
 end
 
-(Duration.from_secs(1) + 41).to_s  # => "42s"
-(Instant.now - 42).to_s            # => "42.000010545s"
+(Duration.secs(1) + 41).to_s  # => "42s"
+(Instant.now - 42).to_s       # => "42.000010545s"
 ```
 
 ## Development
@@ -150,3 +164,19 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/Freaky
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## See Also
+
+### Core Ruby
+
+For a zero-dependency alternative, see
+[`Process.clock_gettime`](https://ruby-doc.org/core-2.6.3/Process.html#method-c-clock_gettime).
+`monotime` currently only uses `Process::CLOCK_MONOTONIC`, but others may offer higher precision
+depending on platform.
+
+### Other Gems
+
+[hitimes](https://rubygems.org/gems/hitimes) is a popular and mature alternative
+which also includes a variety of features for gathering statistics about
+measurements, and may offer higher precision on some platforms.
+

data/lib/monotime/duration.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+module Monotime
+  # A type representing a span of time in nanoseconds.
+  class Duration
+    include Comparable
+
+    # Create a new +Duration+ of a specified number of nanoseconds, zero by
+    # default.
+    #
+    # Users are strongly advised to use +#from_nanos+ instead.
+    #
+    # @param nanos [Integer]
+    # @see #from_nanos
+    def initialize(nanos = 0)
+      @ns = Integer(nanos)
+      freeze
+    end
+
+    class << self
+      # Generate a new +Duration+ measuring the given number of seconds.
+      #
+      # @param secs [Numeric]
+      # @return [Duration]
+      def from_secs(secs)
+        new(Integer(secs * 1_000_000_000))
+      end
+
+      alias secs from_secs
+
+      # Generate a new +Duration+ measuring the given number of milliseconds.
+      #
+      # @param millis [Numeric]
+      # @return [Duration]
+      def from_millis(millis)
+        new(Integer(millis * 1_000_000))
+      end
+
+      alias millis from_millis
+
+      # Generate a new +Duration+ measuring the given number of microseconds.
+      #
+      # @param micros [Numeric]
+      # @return [Duration]
+      def from_micros(micros)
+        new(Integer(micros * 1_000))
+      end
+
+      alias micros from_micros
+
+      # Generate a new +Duration+ measuring the given number of nanoseconds.
+      #
+      # @param nanos [Numeric]
+      # @return [Duration]
+      def from_nanos(nanos)
+        new(Integer(nanos))
+      end
+
+      alias nanos from_nanos
+
+      # Return a +Duration+ measuring the elapsed time of the yielded block.
+      #
+      # @example
+      #   Duration.measure { sleep(0.5) }.to_s # => "512.226109ms"
+      #
+      # @return [Duration]
+      def measure
+        Instant.now.tap { yield }.elapsed
+      end
+
+      # Return the result of the yielded block alongside a +Duration+.
+      #
+      # @example
+      #   Duration.with_measure { "bloop" } # => ["bloop", #<Monotime::Duration: ...>]
+      #
+      # @return [Object, Duration]
+      def with_measure
+        start = Instant.now
+        ret = yield
+        [ret, start.elapsed]
+      end
+    end
+
+    # Add another +Duration+ or +#to_nanos+-coercible object to this one,
+    # returning a new +Duration+.
+    #
+    # @example
+    #   (Duration.from_secs(10) + Duration.from_secs(5)).to_s # => "15s"
+    #
+    # @param [Duration, #to_nanos]
+    # @return [Duration]
+    def +(other)
+      raise TypeError, 'Not one of: [Duration, #to_nanos]' unless other.respond_to?(:to_nanos)
+
+      Duration.new(to_nanos + other.to_nanos)
+    end
+
+    # Subtract another +Duration+ or +#to_nanos+-coercible object from this one,
+    # returning a new +Duration+.
+    #
+    # @example
+    #   (Duration.from_secs(10) - Duration.from_secs(5)).to_s # => "5s"
+    #
+    # @param [Duration, #to_nanos]
+    # @return [Duration]
+    def -(other)
+      raise TypeError, 'Not one of: [Duration, #to_nanos]' unless other.respond_to?(:to_nanos)
+
+      Duration.new(to_nanos - other.to_nanos)
+    end
+
+    # Divide this duration by a +Numeric+.
+    #
+    # @example
+    #   (Duration.from_secs(10) / 2).to_s # => "5s"
+    #
+    # @param [Numeric]
+    # @return [Duration]
+    def /(other)
+      Duration.new(to_nanos / other)
+    end
+
+    # Multiply this duration by a +Numeric+.
+    #
+    # @example
+    #   (Duration.from_secs(10) * 2).to_s # => "20s"
+    #
+    # @param [Numeric]
+    # @return [Duration]
+    def *(other)
+      Duration.new(to_nanos * other)
+    end
+
+    # Unary minus: make a positive +Duration+ negative, and vice versa.
+    #
+    # @example
+    #   -Duration.from_secs(-1).to_s # => "1s"
+    #   -Duration.from_secs(1).to_s  # => "-1s"
+    #
+    # @return [Duration]
+    def -@
+      Duration.new(-to_nanos)
+    end
+
+    # Return a +Duration+ that's absolute (positive).
+    #
+    # @example
+    #   Duration.from_secs(-1).abs.to_s # => "1s"
+    #   Duration.from_secs(1).abs.to_s  # => "1s"
+    #
+    # @return [Duration]
+    def abs
+      return self if positive? || zero?
+
+      Duration.new(to_nanos.abs)
+    end
+
+    # Compare the *value* of this +Duration+ with another, or any +#to_nanos+-coercible
+    # object, or nil if not comparable.
+    #
+    # @param [Duration, #to_nanos, Object]
+    # @return [-1, 0, 1, nil]
+    def <=>(other)
+      to_nanos <=> other.to_nanos if other.respond_to?(:to_nanos)
+    end
+
+    # Compare the equality of the *value* of this +Duration+ with another, or
+    # any +#to_nanos+-coercible object, or nil if not comparable.
+    #
+    # @param [Duration, #to_nanos, Object]
+    # @return [Boolean]
+    def ==(other)
+      other.respond_to?(:to_nanos) && to_nanos == other.to_nanos
+    end
+
+    # Check equality of the value and type of this +Duration+ with another.
+    #
+    # @param [Duration, Object]
+    # @return [Boolean]
+    def eql?(other)
+      other.is_a?(Duration) && to_nanos == other.to_nanos
+    end
+
+    # Generate a hash for this type and value.
+    #
+    # @return [Integer]
+    def hash
+      self.class.hash ^ to_nanos.hash
+    end
+
+    # Return this +Duration+ in seconds.
+    #
+    # @return [Float]
+    def to_secs
+      to_nanos / 1_000_000_000.0
+    end
+
+    alias secs to_secs
+
+    # Return this +Duration+ in milliseconds.
+    #
+    # @return [Float]
+    def to_millis
+      to_nanos / 1_000_000.0
+    end
+
+    alias millis to_millis
+
+    # Return this +Duration+ in microseconds.
+    #
+    # @return [Float]
+    def to_micros
+      to_nanos / 1_000.0
+    end
+
+    alias micros to_micros
+
+    # Return this +Duration+ in nanoseconds.
+    #
+    # @return [Integer]
+    def to_nanos
+      @ns
+    end
+
+    alias nanos to_nanos
+
+    # Return true if this +Duration+ is positive.
+    #
+    # @return [Boolean]
+    def positive?
+      to_nanos.positive?
+    end
+
+    # Return true if this +Duration+ is negative.
+    #
+    # @return [Boolean]
+    def negative?
+      to_nanos.negative?
+    end
+
+    # Return true if this +Duration+ is zero.
+    #
+    # @return [Boolean]
+    def zero?
+      to_nanos.zero?
+    end
+
+    # Return true if this +Duration+ is non-zero.
+    #
+    # @return [Boolean]
+    def nonzero?
+      to_nanos.nonzero?
+    end
+
+    # Sleep for the duration of this +Duration+.  Equivalent to
+    # +Kernel.sleep(duration.to_secs)+.
+    #
+    # @example
+    #   Duration.from_secs(1).sleep  # => 1
+    #   Duration.from_secs(-1).sleep # => raises NotImplementedError
+    #
+    # @raise [NotImplementedError] negative +Duration+ sleeps are not yet supported.
+    # @return [Integer]
+    # @see Instant#sleep
+    def sleep
+      raise NotImplementedError, 'time travel module missing' if negative?
+
+      Kernel.sleep(to_secs)
+    end
+
+    DIVISORS = [
+      [1_000_000_000.0, 's'],
+      [1_000_000.0, 'ms'],
+      [1_000.0, 'μs'],
+      [0, 'ns']
+    ].map(&:freeze).freeze
+
+    private_constant :DIVISORS
+
+    # Format this +Duration+ into a human-readable string, with a given number
+    # of decimal places.
+    #
+    # The exact format is subject to change, users with specific requirements
+    # are encouraged to use their own formatting methods.
+    #
+    # @example
+    #   Duration.from_nanos(100).to_s  # => "100ns"
+    #   Duration.from_micros(100).to_s # => "100μs"
+    #   Duration.from_millis(100).to_s # => "100ms"
+    #   Duration.from_secs(100).to_s   # => "100s"
+    #   Duration.from_nanos(1234567).to_s # => "1.234567ms"
+    #   Duration.from_nanos(1234567).to_s(2) # => "1.23ms"
+    #
+    # @param precision [Integer] the maximum number of decimal places
+    # @return [String]
+    def to_s(precision = 9)
+      precision = Integer(precision).abs
+      div, unit = DIVISORS.find { |d, _| to_nanos.abs >= d }
+
+      if div.zero?
+        format('%d%s', to_nanos, unit)
+      else
+        format("%#.#{precision}f", to_nanos / div).sub(/\.?0*\z/, '') << unit
+      end
+    end
+  end
+end

data/lib/monotime/include.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'monotime'
+
+include Monotime