monotime 0.8.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 388a55af121b75e9a9ac06db8674e5a8a4b06ade0431a5cdd961f82426c87ade
-  data.tar.gz: 7d62a9b673252f01591769d8659c5a36b1026088724a2afc9694b41f633ca053
+  metadata.gz: fa145221981b5ff0adb6d1cd3aa77a7e9e9a32942ab9a849a2f83a0d434e245d
+  data.tar.gz: c86e6a4ca11e2e9569089574662e96d2cf0ef1b2216ee638832099a5570cd5da
 SHA512:
-  metadata.gz: 14c7ede1fc2daa4fef854d3be58392f57849ff07c4f815c3e995f32073e14893fa7ad95f08e074199457517d262fc8c2942316b8039260b1e66e4045409bb6cf
-  data.tar.gz: b2c907ce1b4f3f92185ba4cb238c3809b465d40be7e34eb1c4a225779a4f6c156ae1d78742ddf24a467d59bfd3437c15be54d4f8bc91a9a9d06fa42ee5e5544a
+  metadata.gz: 78a3a8dc8817cc0f99b67d2839d341e01259815c1fefce78ad0d619f2a4c2739414896a98322a2dd620d105b3b1636f6d355d2250deb71920e3a444d970bc0c4
+  data.tar.gz: 5408bc28e13df38a04228eedd325371f7136c036c6ab57c0775c7adc401d4e516acae375502bf16d1f5e3945fe2aaf9b60e6e8549d57570a16d4ec59b10a5b99

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.8.2] - 2023-09-22
+
+### Added
+
+- `Instant.clock_name` is back and now tracks `clock_id` using reflection.
+- Explicit minimum Ruby version in gemspec (2.7.0).
+
+### Changed
+
+- Clock auto-selection redux. We choose the first available from:
+
+  1. `CLOCK_UPTIME_RAW` on macOS, faster and higher resolution, also used by Rust
+  2. `CLOCK_MONOTONIC`
+  3. `CLOCK_REALTIME`, a non-monotonic fallback that issues a warning on startup
+
+- Slight performance bump for `Duration.measure` on Ruby <= 3.1
+
+## [0.8.1] - 2023-09-18
+
+### Changed
+
+- After further consideration, return to defaulting to `CLOCK_MONOTONIC` instead
+  of the overly-elaborate auto-selection introduced in 0.8.0.
+
+### Removed
+
+- `Instant.clock_name`.  No I'm not incrementing to 0.9.  It's been a few hours,
+   you're not using it, shut up.
+
 ## [0.8.0] - 2023-09-17
 
 ### Added
@@ -165,8 +194,11 @@
 [0.6.1]: https://github.com/Freaky/monotime/commits/v0.6.1
 [0.7.0]: https://github.com/Freaky/monotime/commits/v0.7.0
 [0.7.1]: https://github.com/Freaky/monotime/commits/v0.7.0
-[0.8.0]: https://github.com/Freaky/monotime/commits/v0.7.0
+[0.8.0]: https://github.com/Freaky/monotime/commits/v0.8.0
+[0.8.1]: https://github.com/Freaky/monotime/commits/v0.8.1
+[0.8.2]: https://github.com/Freaky/monotime/commits/v0.8.2
 [issue #1]: https://github.com/Freaky/monotime/issues/1
+[Ruby #16740]: https://bugs.ruby-lang.org/issues/16740
 [@celsworth]: https://github.com/celsworth
 [@petergoldstein]: https://github.com/petergoldstein
-[@fig]: https://github.com/fig
+[@fig]: https://github.com/fig

data/README.md

@@ -171,11 +171,11 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ### Core Ruby
 
 For a zero-dependency alternative upon which `monotime` is based, see
-[`Process.clock_gettime`](https://ruby-doc.org/core-2.6.3/Process.html#method-c-clock_gettime).
+[`Process.clock_gettime`](https://www.rubydoc.info/stdlib/core/Process:clock_gettime).
 
-`Process::CLOCK_MONOTONIC` is a safe default, but other options may offer better
-behaviour in face of NTP frequency skew or suspend/resume and should be evaluated
-carefully.
+`Process::CLOCK_MONOTONIC` is a safe default, but other options may offer higher
+resolution or alternative behaviour in light of system suspend/resume or NTP
+frequency skew.
 
 ### Other Gems
 

data/lib/monotime/duration.rb

@@ -106,7 +106,9 @@ module Monotime
       #
       # @return [Duration]
       def measure
-        Instant.now.tap { yield }.elapsed
+        start = Instant.now
+        yield
+        start.elapsed
       end
 
       # Return the result of the yielded block alongside a +Duration+.

data/lib/monotime/instant.rb

@@ -12,38 +12,16 @@ module Monotime
     include Comparable
 
     class << self
-      attr_writer :clock_id
-
-      # The symbolic name of the automatically-selected +Process.clock_gettime+
-      # clock id, if available.  This will *not* reflect a manually-set +clock_id+.
-      #
-      # @return [Symbol, nil]
-      attr_reader :clock_name
-
-      # The function used to create +Instant+ instances.
-      #
-      # This function must return a +Numeric+, monotonic count of nanoseconds
-      # since a fixed point in the past.
-      #
-      # Defaults to `lambda { Process.clock_gettime(clock_id, :nanosecond) }`.
-      #
-      # @overload monotonic_function=(function)
-      #   @param function [#call]
-      attr_accessor :monotonic_function
-
       # @overload clock_id
-      #   The configured or detected +Process.clock_getime+ clock identifier.
-      #
-      #   Raises +NotImplementedError+ if a suitable monotonic clock source cannot
-      #   be found and one has not been specified manually.
+      #   The +Process.clock_gettime+ clock id used to create +Instant+ instances
+      #   by the default monotonic function.
       #
       #   @return [Numeric]
       #
       # @overload clock_id=(id)
-      #   The +Process.clock_gettime+ clock id used to create +Instant+ instances
-      #   by the default monotonic function.
       #
-      #   Suggested options include but are not limited to:
+      #   Override the default +Process.clock_gettime+ clock id.  Some potential
+      #   choices include but are not limited to:
       #
       #   * +Process::CLOCK_MONOTONIC_RAW+
       #   * +Process::CLOCK_UPTIME_RAW+
@@ -53,56 +31,85 @@ module Monotime
       #   * +Process::CLOCK_MONOTONIC_PRECISE+
       #   * +Process::CLOCK_MONOTONIC_FAST+
       #   * +Process::CLOCK_MONOTONIC+
+      #   * +:MACH_ABSOLUTE_TIME_BASED_CLOCK_MONOTONIC+
+      #   * +:TIMES_BASED_CLOCK_MONOTONIC+
       #
-      #   These are platform-dependant and may vary in resolution, performance,
-      #   and behaviour from NTP frequency skew and system suspend/resume.
+      #   These are platform-dependant and may vary in resolution, accuracy,
+      #   performance, and behaviour in light of system suspend/resume and NTP
+      #   frequency skew.  They should be selected carefully based on your specific
+      #   needs and environment.
       #
       #   It is possible to set non-monotonic clock sources here.  You probably
       #   shouldn't.
       #
-      #   Defaults to auto-detect.
+      #   Defaults to auto-selection from whatever is available from:
       #
-      #   @param id [Numeric]
-      def clock_id
-        @clock_id ||= detect_clock_id
-      end
+      #   * +CLOCK_UPTIME_RAW+ (if running under macOS)
+      #   * +CLOCK_MONOTONIC+
+      #   * +CLOCK_REALTIME+ (non-monotonic fallback, issues a run-time warning)
+      #
+      #   @param id [Numeric, Symbol]
+      attr_accessor :clock_id
+
+      # The function used to create +Instant+ instances.
+      #
+      # This function must return a +Numeric+, monotonic count of nanoseconds
+      # since a fixed point in the past.
+      #
+      # Defaults to +-> { Process.clock_gettime(clock_id, :nanosecond) }+.
+      #
+      # @overload monotonic_function=(function)
+      #   @param function [#call]
+      attr_accessor :monotonic_function
 
       # Return the claimed resolution of the given clock id or the configured
       # +clock_id+, as a +Duration+, or +nil+ if invalid.
       #
-      # @param clock [Numeric] Optional clock id instead of default.
-      def clock_getres(clock = @clock_id)
+      # Note per Ruby issue #16740, the practical usability of this method is
+      # dubious and non-portable.
+      #
+      # @param clock [Numeric, Symbol] Optional clock id instead of default.
+      def clock_getres(clock = clock_id)
         Duration.from_nanos(Process.clock_getres(clock, :nanosecond))
       rescue SystemCallError
         # suppress errors
       end
 
-      private
+      # The symbolic name of the currently-selected +clock_id+, if available.
+      #
+      # @return [Symbol, nil]
+      def clock_name
+        return clock_id if clock_id.is_a? Symbol
+
+        Process.constants.find do |c|
+          c.to_s.start_with?('CLOCK_') && Process.const_get(c) == clock_id
+        end
+      end
 
-      def detect_clock_id
-        name, id, =
-          [
-            :CLOCK_MONOTONIC_RAW,     # Linux, not affected by NTP frequency adjustments
-            :CLOCK_UPTIME_RAW,        # macOS, not affected by NTP frequency adjustments
-            :CLOCK_UPTIME_PRECISE,    # FreeBSD, increments while system is running
-            :CLOCK_UPTIME,            # OpenBSD, increments while system is running
-            :CLOCK_MONOTONIC_PRECISE, # FreeBSD, precise monotonic clock
-            :CLOCK_MONOTONIC,         # Standard cross-platform monotonic clock
-          ]
-          .each_with_index # Used to force a stable sort in min_by
-          .filter { |name, _| Process.const_defined?(name) }
-          .map { |name, index| [name, Process.const_get(name), index] }
-          .filter_map { |clock| clock.insert(2, clock_getres(clock[1])) }
-          .min_by { |clock| clock[2..] } # find smallest resolution and index
-          .tap { |clock| raise NotImplementedError, 'No usable clock' unless clock }
+      private
 
-        @clock_name = name
-        id
+      def select_clock_id
+        if RUBY_PLATFORM.include?('darwin') && Process.const_defined?(:CLOCK_UPTIME_RAW)
+          # Offers nanosecond resolution and appears to be slightly faster on two
+          # different Macs (M1 and x64)
+          #
+          # There is also :MACH_ABSOLUTE_TIME_BASED_CLOCK_MONOTONIC which calls
+          # mach_absolute_time() directly, but documentation for that recommends
+          # CLOCK_UPTIME_RAW, and the performance difference is minimal.
+          Process::CLOCK_UPTIME_RAW
+        elsif Process.const_defined?(:CLOCK_MONOTONIC)
+          Process::CLOCK_MONOTONIC
+        else
+          # There is also :TIMES_BASED_CLOCK_MONOTONIC, but having seen it just return
+          # 0 instead of an error on a MSVC build this may be the safer option.
+          warn 'No monotonic clock source detected, falling back to CLOCK_REALTIME'
+          Process::CLOCK_REALTIME
+        end
       end
     end
 
     self.monotonic_function = -> { Process.clock_gettime(clock_id, :nanosecond) }
-    clock_id # detect our clock_id early
+    self.clock_id = select_clock_id
 
     # Create a new +Instant+ from an optional nanosecond measurement.
     #

data/lib/monotime/version.rb

@@ -2,5 +2,5 @@
 
 module Monotime
   # Version of the `monotime` gem
-  MONOTIME_VERSION = '0.8.0'
+  MONOTIME_VERSION = '0.8.2'
 end

data/monotime.gemspec

@@ -13,6 +13,8 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/Freaky/monotime"
   spec.license       = "MIT"
 
+  spec.required_ruby_version = '>= 2.7.0'
+
   # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
   # to allow pushing to a single host or delete this section to allow pushing to any host.
   if spec.respond_to?(:metadata)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monotime
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.2
 platform: ruby
 authors:
 - Thomas Hurst
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-17 00:00:00.000000000 Z
+date: 2023-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -102,14 +102,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.4.18
 signing_key:
 specification_version: 4
 summary: A sensible interface to the monotonic clock