hitimes 1.3.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e479c2fbfddbd9d35a7f9bcc4580b265f43cd9fa46a7a986e1d10401c58b882
-  data.tar.gz: 5751466c5f9a518a607b4f14df5e368dd85d990fccbc665f6d080b5435982b4d
+  metadata.gz: d79a16734531380e103efb7bf1af93e5c4e465185f5a47f1c0ab6d2dcc8bb5e7
+  data.tar.gz: deb8a23bdc8e0f35b6dccbd6fd4535ffdfa4c5bdd11ff44fa488a53baa090245
 SHA512:
-  metadata.gz: fabe96db83fec72aac45648908229119bce50fdef39e61fc00f426a7d44ba3da791be416b5e44f0c6bd4cae822e241e152f827c490fb46658946a910ffad6579
-  data.tar.gz: e1ba6e894dbabf0911df83bbae59a9dfd201b2edfd605a2fe9c27f46e2d5d5bf80105918f3a718df02de0fccf975cc36ada85254b53f949ce78036fe9130d050
+  metadata.gz: 358edcfe776e98c69100f01065d5f9ac12452353736180f8bf1d04e240cddc1bafcc43078b949c26ef40709acce3f2ac28bb65fed28a7e45301dd2a9c607a4ac
+  data.tar.gz: 3c6296fd094227654048f8bda301435442d6c0169b12322253ba07b1486a4137549ff4f3f11e7f5f09cd3c12f4a78eb92ba9055ebd99d5b6a4eab452ac4f16db

data/CONTRIBUTING.md

@@ -27,23 +27,12 @@ easiest way to contribute.
 * Fork the [repo][].
 * Create a new branch for your issue: `git checkout -b issue/my-issue`
 * Lovingly craft your contribution:
-    * `rake develop` to get started
+    * `bin/setup` to get started
     * `rake test` to run tests
 * Make sure that `rake test` passes. Its important, I said it twice.
 * Add yourself to the contributors section below.
 * Submit your [pull request][].
 
-## Building Windows Binaries
-
-This is done using https://github.com/rake-compiler/rake-compiler-dock
-
-1. have VirtualBox installed
-2. have Docker Machine installed (https://docs.docker.com/engine/installation/)
-3. `gem install rake-compiler-dock`
-4. `rake-compiler-dock` (this could take a while)
-5. `bundle`
-6. `rake cross native gem`
-
 # Contributors
 
 * Jeremy Hinegardner

data/HISTORY.md

@@ -1,4 +1,28 @@
 # Hitimes Changelog
+## Version 3.0.0 - 2024-05-01
+
+* Migrated to SemaphoreCI for doing full test runs on all active ruby versions.
+* Remove the dependency on `Process.clock_getres` as it is unreliable.
+* This has the effect of deprecating some Hitimes constants that had been documented as public. These are now removed as this is a major version update
+  - `Hitimes::CLOCK_RESOLUTION_NANOSECONDS`
+  - `Hitimes::CLOCK_RESOLUTION_SECONDS`
+  - `Hitimes::INSTANT_CONVERSION_FACTOR`
+  - `Hitimes.clock_resolution_description`
+  - `Hitimes.clock_description`
+* Added Rubocop for some coding consistency
+* Updated the supported ruby version to be 3.0 and up
+* Updated all dependencies
+* Changed how all the `assert_delta` style tests were done so they were not so flakey
+* Hitimes will now emit a `warn` message if it ends up using `CLOCK_REALTIME`
+* Hitimes will raise an exception if it cannot find a valid clock id. This is a bug and a message to file a report is in the exception
+
+## Version 2.0.0 2019-09-23
+
+* Remove the C and Java extensions as `Process.clock_gettime()` has the same
+  resolution as what the extensions did.
+* Update all depedencies and resolve deprecations
+* Now usable on truffleruby
+
 ## Version 1.3.1 2019-01-18
 
 * Update jruby extension to not use global runtime state (thanks @kares) (#70)
@@ -76,7 +100,7 @@
 
 ## Version 1.0.3 2009-06-28
 
-* Fix bug with time.h on linode (reported by Roger Pack) 
+* Fix bug with time.h on linode (reported by Roger Pack)
 * Fix potential garbage collection issue with Interval class
 * Windows gem is now a fat binary to support installing in 1.8 or 1.9 from the
   same gem
@@ -105,7 +129,7 @@
 
 * Added new stat 'rate'
 * Added new stat method to_hash
-* Added Hitimes::MutexedStats class for threadsafe stats collection 
+* Added Hitimes::MutexedStats class for threadsafe stats collection
     - not needed when used in MRI 1.8.x
 * remove stale dependency on mkrf
 

data/Manifest.txt

@@ -1,25 +1,13 @@
 CONTRIBUTING.md
 HISTORY.md
-LICENSE
+LICENSE.txt
 Manifest.txt
 README.md
-Rakefile
-examples/benchmarks.rb
-examples/stats.rb
-ext/hitimes/c/extconf.rb
-ext/hitimes/c/hitimes.c
-ext/hitimes/c/hitimes_instant_clock_gettime.c
-ext/hitimes/c/hitimes_instant_osx.c
-ext/hitimes/c/hitimes_instant_windows.c
-ext/hitimes/c/hitimes_interval.c
-ext/hitimes/c/hitimes_interval.h
-ext/hitimes/c/hitimes_stats.c
-ext/hitimes/c/hitimes_stats.h
-ext/hitimes/java/src/hitimes/Hitimes.java
-ext/hitimes/java/src/hitimes/HitimesInterval.java
-ext/hitimes/java/src/hitimes/HitimesService.java
-ext/hitimes/java/src/hitimes/HitimesStats.java
+hitimes.gemspec
 lib/hitimes.rb
+lib/hitimes/initialize.rb
+lib/hitimes/instant.rb
+lib/hitimes/interval.rb
 lib/hitimes/metric.rb
 lib/hitimes/mutexed_stats.rb
 lib/hitimes/paths.rb
@@ -28,17 +16,3 @@ lib/hitimes/timed_metric.rb
 lib/hitimes/timed_value_metric.rb
 lib/hitimes/value_metric.rb
 lib/hitimes/version.rb
-spec/hitimes_spec.rb
-spec/interval_spec.rb
-spec/metric_spec.rb
-spec/mutex_stats_spec.rb
-spec/paths_spec.rb
-spec/spec_helper.rb
-spec/stats_spec.rb
-spec/timed_metric_spec.rb
-spec/timed_value_metric_spec.rb
-spec/value_metric_spec.rb
-spec/version_spec.rb
-tasks/default.rake
-tasks/extension.rake
-tasks/this.rb

data/README.md

@@ -1,17 +1,14 @@
 # Hitimes
+[![Build Status](https://copiousfreetime.semaphoreci.com/badges/hitimes/branches/main.svg)](https://copiousfreetime.semaphoreci.com/projects/hitimes)
 
-[![Build Status](https://travis-ci.org/copiousfreetime/hitimes.svg?branch=master)](https://travis-ci.org/copiousfreetime/hitimes)
-
-## Description
+* [Homepage](http://github.com/copiousfreetime/hitimes)
+* [Github project](http://github.com/copiousfreetime/hitimes)
 
-A fast, high resolution timer library for recording peformance metrics.
+## DESCRIPTION
 
-* [Homepage](http://github.com/copiousfreetime/hitimes)
-* [Github project](http://github.com.org/copiousfreetime/hitimes)
-* email jeremy at copiousfreetime dot org
-* `git clone url git://github.com/copiousfreetime/hitimes.git`
+A fast, high resolution timer library for recording performance metrics.
 
-## Table of Contents
+## TABLE OF CONTENTS
 
 * [Requirements](#requirements)
 * [Usage](#usage)
@@ -20,13 +17,13 @@ A fast, high resolution timer library for recording peformance metrics.
 * [License](#license)
 
 
-## Requirements
+## REQUIREMENTS
 
 Hitimes requires the following to run:
 
   * Ruby
 
-## Usage
+## USAGE
 
 Hitimes easiest to use when installed with `rubygems`:
 
@@ -37,13 +34,13 @@ gem install hitimes
 Or as part of your bundler `Gemfile`:
 
 ```ruby
-gem 'hitimes'
+gem "hitimes"
 ```
 
 You can load it with the standard ruby require statement.
 
 ```ruby
-require 'hitimes'
+require "hitimes"
 ```
 
 ### Interval
@@ -53,10 +50,10 @@ Returns the time as seconds.
 
 ```ruby
 duration = Hitimes::Interval.measure do
-             1_000_000.times do |x|
-               2 + 2
-             end
-           end
+  1_000_000.times do |x|
+    2 + 2
+  end
+end
 
 puts duration  # => 0.047414297 (seconds)
 ```
@@ -66,7 +63,7 @@ puts duration  # => 0.047414297 (seconds)
 Use a `Hitimes::TimedMetric` to calculate statistics about an iterative operation
 
 ```ruby
-timed_metric = Hitimes::TimedMetric.new('operation on items')
+timed_metric = Hitimes::TimedMetric.new("operation on items")
 ```
 
 Explicitly use `start` and `stop`:
@@ -84,7 +81,8 @@ value of the block.
 
 ```ruby
 collection.each do |item|
-  result_of_do_something = timed_metric.measure { do_something( item ) }
+  result_of_do_something = timed_metric.measure { do_something(item) }
+  # do something with result_of_do_something
 end
 ```
 And then look at the stats
@@ -96,15 +94,16 @@ puts timed_metric.min
 puts timed_metric.stddev
 puts timed_metric.rate
 ```
+
 ### ValueMetric
 
 Use a `Hitimes::ValueMetric` to calculate statistics about measured samples.
 
 ``` ruby
-value_metric = Hitimes::ValueMetric.new( 'size of thing' )
+value_metric = Hitimes::ValueMetric.new("size of thing")
 loop do
   # ... do stuff changing sizes of 'thing'
-  value_metric.measure( thing.size )
+  value_metric.measure(thing.size)
   # ... do other stuff that may change size of thing
 end
 
@@ -120,12 +119,12 @@ puts value_metric.rate
 Use a `Hitimes::TimedValueMetric` to calculate statistics about batches of samples.
 
 ``` ruby
-timed_value_metric = Hitimes::TimedValueMetric.new( 'batch times' )
-loop do 
+timed_value_metric = Hitimes::TimedValueMetric.new("batch times")
+loop do
   batch = ... # get a batch of things
   timed_value_metric.start
   # .. do something with batch
-  timed_value_metric.stop( batch.size )
+  timed_value_metric.stop(batch.size)
 end
 
 puts timed_value_metric.rate
@@ -143,60 +142,46 @@ puts timed_value_metric.value_stats.stddev
 
 ### Implementation details
 
-Hitimes use the appropriate low-level system call for each operating system to
+Hitimes uses the internal ruby `Process::clock_gettime()` to
 get the highest granularity time increment possible. Generally this is
-nanosecond resolution, or whatever the hardware chip in the CPU supports.
-
-It currently supports any of the following systems:
+nanosecond resolution, or whatever the hardware in the CPU supports.
 
-* any system with the POSIX call `clock_gettime()`
-* Mac OS X
-* Windows
-* JRuby
-
-## Support
+## SUPPORT
 
 Hitimes is supported on whatever versions of ruby are currently supported.
 Hitimes also follows [semantic versioning](http://semver.org/).
 
 The current officially supported versions of Ruby are:
 
-* MRI Ruby (all platforms) 2.3 - 2.6
-* JRuby 9.1.17.0, 9.2.X.X
+* MRI Ruby (all platforms) 3.0 - current
+* JRuby 9.4.x.x
+* Truffleruby 24
 
-Unofficially supported versions, these have been supported in the past when they
-were the primary rubies around. In all likelihood they still work, but are not
-supported.
+Unofficially supported versions, any version of MRI from Ruby 2.1 and up. Since
+the C Extension has been removed Hitimes should work with any ruby that is 2.1
+or greater as that is when `Process.clock_gettime()` was implemented.
 
-* MRI Ruby (linux/mac/bsd/unix/etc) - everything from 1.8.7 to 2.2
-* MRI Ruby (windows) - 2.0 and up
-  * Ruby 1.8 and 1.9 for windows are supported in hitimes version 1.2.4 or earlier
-* JRuby - I think everything back to 1.4
-* Rubinius
+For versions of Ruby before 2.1 please use Hitimes 1.3, the extension code is
+still in there and they should still work.
 
-## Contributing
+## CONTRIBUTING
 
-Please read the [CONTRIBUTING.md](CONTRIBUTING.md)
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on development
+and bug reporting.
 
 ## Credits
 
-* [Bruce Williams](https://github.com/bruce) for suggesting the idea
+* [Bruce Williams](https://github.com/bruce) for suggesting the idea.
+* [Benoit Daloze](https://github.com/eregon) and [Thomas Hurst](https://github.com/Freaky) for conversations around clock_ids.
 
 ## License
 
 Hitimes is licensed under the [ISC](https://opensource.org/licenses/ISC)
 license.
 
-Copyright (c) 2008-2016 Jeremy Hinegardner
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
+## Related Works
 
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
-FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
+* [monotime](https://github.com/Freaky/monotime) - A sensible interface to Ruby's monotonic clock.
+* [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) - [Concurrent.monotonic_time](https://github.com/ruby-concurrency/concurrent-ruby) is a straight pass through to `Process.clock_gettime(Process::CLOCK_MONOTONIC,...)`.
+* [Instant](https://doc.rust-lang.org/src/std/time.rs.html) - The rust equivalent.
+* [time.Now](https://pkg.go.dev/time) - The go monotonic time interface is part of this package.

data/hitimes.gemspec

@@ -0,0 +1,26 @@
+# DO NOT EDIT - This file is automatically generated
+# Make changes to Manifest.txt and/or Rakefile and regenerate
+# -*- encoding: utf-8 -*-
+# stub: hitimes 3.0.0 ruby lib
+
+Gem::Specification.new do |s|
+  s.name = "hitimes".freeze
+  s.version = "3.0.0".freeze
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
+  s.metadata = { "bug_tracker_uri" => "https://github.com/copiousfreetime/hitimes/issues", "changelog_uri" => "https://github.com/copiousfreetime/hitimes/blob/master/HISTORY.md", "homepage_uri" => "https://github.com/copiousfreetime/hitimes", "source_code_uri" => "https://github.com/copiousfreetime/hitimes" } if s.respond_to? :metadata=
+  s.require_paths = ["lib".freeze]
+  s.authors = ["Jeremy Hinegardner".freeze]
+  s.bindir = "exe".freeze
+  s.date = "2024-05-01"
+  s.description = "A fast, high resolution timer library for recording performance metrics.".freeze
+  s.email = "jeremy@copiousfreetime.org".freeze
+  s.extra_rdoc_files = ["CONTRIBUTING.md".freeze, "HISTORY.md".freeze, "LICENSE.txt".freeze, "Manifest.txt".freeze, "README.md".freeze]
+  s.files = ["CONTRIBUTING.md".freeze, "HISTORY.md".freeze, "LICENSE.txt".freeze, "Manifest.txt".freeze, "README.md".freeze, "hitimes.gemspec".freeze, "lib/hitimes.rb".freeze, "lib/hitimes/initialize.rb".freeze, "lib/hitimes/instant.rb".freeze, "lib/hitimes/interval.rb".freeze, "lib/hitimes/metric.rb".freeze, "lib/hitimes/mutexed_stats.rb".freeze, "lib/hitimes/paths.rb".freeze, "lib/hitimes/stats.rb".freeze, "lib/hitimes/timed_metric.rb".freeze, "lib/hitimes/timed_value_metric.rb".freeze, "lib/hitimes/value_metric.rb".freeze, "lib/hitimes/version.rb".freeze]
+  s.homepage = "http://github.com/copiousfreetime/hitimes".freeze
+  s.licenses = ["ISC".freeze]
+  s.rdoc_options = ["--main".freeze, "README.md".freeze, "--markup".freeze, "tomdoc".freeze]
+  s.required_ruby_version = Gem::Requirement.new(">= 3.0.0".freeze)
+  s.rubygems_version = "3.5.9".freeze
+  s.summary = "A fast, high resolution timer library for recording performance metrics.".freeze
+end

data/lib/hitimes/initialize.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Hitimes
+  # Internal: Internal setup that is done when the library is loaded
+  #
+  # We want to determine what clock to use for this machine. So we need to
+  # introspect the ruby environment and then setup some initial constants. These
+  # methods are used in lib/hitimes/instant.rb to help setup the CLOCK_ID
+  # constant at load time.
+  #
+  module Initialize
+    #
+    # After a fair bit of experimentaiton, it seems that the only clock_ids that
+    # are of any use are the following:
+    #
+    # POSIX:
+    #
+    #   CLOCK_REALTIME   A settable system-wide real-time clock. Measures
+    #                    wall-clock time. Affected by system jumps in time,
+    #                    adjtime(3), and NTP.
+    #
+    #   CLOCK_MONOTONIC  A nonsettable system-wide clock that represent
+    #                    monotomic time since some unspecified point in the
+    #                    past. Not affected by jumps in system time, but is
+    #                    affectd by adjtime(3) and NTP.
+    #
+    # Darwin:
+    #
+    #   CLOCK_MONOTONIC_RAW  clock that increments monotonically, tracking the
+    #                        time since an arbitrary point like CLOCK_MONOTONIC.
+    #                        However, this clock is unaffected by frequency or
+    #                        time adjustments.
+    #
+    #   CLOCK_UPTIME_RAW  clock that increments monotonically, in the same manner
+    #                     as CLOCK_MONOTONIC_RAW, but that does not increment
+    #                     while the system is asleep.  The returned value is
+    #                     identical to the result of mach_absolute_time()
+    #                     after the appropriate mach_timebase conversion is applied.
+    #
+    # Linux:
+    #
+    #   CLOCK_MONOTONIC_RAW  Similar to CLOCK_MONOTONIC, but provides access to
+    #                        a raw hardware-based time that is not subject to NTP
+    #                        adjustments or the incremental adjustments performed
+    #                        by adjtime(3)
+    #
+    #   CLOCK_BOOTTIME  Identical to CLOCK_MONOTONIC, except it also includes any
+    #                   time that the system is suspended.
+    #
+    # *BSD:
+    #
+    #   All the BSDs seem to have CLOCK_MONOTONIC and CLOCK_REALTIME although on
+    #   NetBSD CLOCK_MONOTONIC is not affected by adjtime(2). It is unclear if
+    #   they are affected by adjtime(2) on FreeBSD, OpenBSD, or DragonFlyBSD. -
+    #   at least according to the man pages.
+    #
+    # What this boils down to as that pretty much all systems have CLOCK_REALTIME
+    # and CLOCK_MONOTONIC. The other clocks are system specific and may or may
+    # not exist. We'll try to use the most accurate clock available.
+    #
+    # So we'll try to use the following clocks in order of preference:
+    #
+    # On Linux and Darwin
+    #   CLOCK_MONOTONIC_RAW, CLOCK_MONOTONIC, CLOCK_REALTIME
+    #
+    # Everyone else:
+    #   CLOCK_MONOTONIC, CLOCK_REALTIME
+    #
+    # So in reality, well just test for constants on all of the above and use the
+    # first one that exists.
+    #
+    # If CLOCK_REALTIME is chose, we will dump a warning to the user.
+    # And if we can't finde one, which is really, really odd, we'll raise an exception.
+    POTENTIAL_CLOCK_IDS = %i[CLOCK_MONOTONIC_RAW CLOCK_MONOTONIC CLOCK_REALTIME].freeze
+    def determine_clock_id(potential_ids = POTENTIAL_CLOCK_IDS)
+      sym = potential_ids.find { |id| Process.const_defined?(id) }
+
+      unless sym
+        raise Hitimes::Error, <<~ERROR
+          Unable to find a high resolution clock at all. THIS IS A BUG!!
+
+          RUBY_DESCRIPTION: #{RUBY_DESCRIPTION}
+
+          Please report this bug to the hitimes issue tracker at
+          https://github.com/copiousfreetime/hitimes/issues
+        ERROR
+      end
+
+      if sym == :CLOCK_REALTIME
+        warn <<~TXT
+          Unable to find a high resolution clock. Using CLOCK_REALTIME for timing.
+
+          RUBY_DESCRIPTION: #{RUBY_DESCRIPTION}
+
+          Please report the above information to the hitimes issue tracker at
+          https://github.com/copiousfreetime/hitimes/issues
+        TXT
+      end
+
+      Process.const_get(sym)
+    end
+    module_function :determine_clock_id
+  end
+end

data/lib/hitimes/instant.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "hitimes/initialize"
+
+# Hitimes Constants and module methods
+#
+module Hitimes
+  # Public: The clock_id to use in Process.clock_gettime
+  CLOCK_ID                        = Initialize.determine_clock_id.freeze
+
+  # Internal: The fraction of second of a nanosecond
+  NANOSECONDS_PER_SECOND          = 1e9
+
+  # Public: Get the raw instant
+  #
+  # Examples:
+  #
+  #    Hitimes.raw_instant
+  #
+  # Returns the raw instant value
+  def raw_instant
+    Process.clock_gettime(::Hitimes::CLOCK_ID, :nanosecond)
+  end
+  module_function :raw_instant
+
+  # Internal: The human readable clock name of the CLOCK_ID as a string
+  #
+  # Returns the clock name as a String
+  def clock_name
+    case CLOCK_ID
+    when Symbol
+      CLOCK_ID.to_s
+    else
+      const = Process.constants.grep(/CLOCK/).find do |id|
+        Process.const_get(id) == CLOCK_ID
+      end
+      "Process::#{const}"
+    end
+  end
+  module_function :clock_name
+end

data/lib/hitimes/interval.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#
+module Hitimes
+  # This is the lowest level timing mechanism available.  It allows for easy
+  # measuring based upon a block:
+  #
+  #   duration = Interval.measure { ... }
+  #
+  # Or measuring something specifically
+  #
+  #   interval = Interval.new
+  #   interval.start
+  #   duration = interval.stop
+  #
+  # Allocating and starting an interval can be done in one method call with
+  #
+  #   interval = Interval.now
+  #
+  # Interval is useful when you only need to track a single interval of time, or
+  # if you do not want to track statistics about an operation.
+  class Interval
+    # Public: The integer representing the start instant of the Interval.  This
+    # valuea is not useful on its own.  It is a platform dependent value.
+    attr_reader :start_instant
+
+    # Public: The integer representing the stop instant of the Interval.  This
+    # value is not useful on its own.  It is a platform dependent value.
+    attr_reader :stop_instant
+
+    def initialize(start = nil, stop = nil)
+      @start_instant = start
+      @stop_instant  = stop
+      @duration      = -Float::INFINITY
+    end
+
+    # call-seq:
+    #    Interval.now -> Interval
+    #
+    # Create an interval that has already started
+    #
+    def self.now
+      Interval.new(Hitimes.raw_instant)
+    end
+
+    # call-seq:
+    #    Interval.measure {  }  -> Float
+    #
+    # Times the execution of the block returning the number of seconds it took
+    def self.measure
+      raise Error, "No block given to Interval.measure" unless block_given?
+
+      interval = Interval.now
+      yield
+      interval.stop
+
+      interval.duration
+    end
+
+    # call-seq:
+    #    interval.split -> Interval
+    #
+    # Immediately stop the current interval and start a new interval that has a
+    # start_instant equivalent to the stop_interval of self.
+    def split
+      @stop_instant = ::Hitimes.raw_instant
+      Interval.new(@stop_instant)
+    end
+
+    # call-seq:
+    #    interval.start -> boolean
+    #
+    # mark the start of the interval.  Calling start on an already started
+    # interval has no effect.  An interval can only be started once.  If the
+    # interval is truely started +true+ is returned otherwise +false+.
+    def start
+      return false if started?
+
+      @start_instant = ::Hitimes.raw_instant
+      true
+    end
+
+    # call-seq:
+    #    interval.stop -> bool or Float
+    #
+    # mark the stop of the interval.  Calling stop on an already stopped interval
+    # has no effect.  An interval can only be stopped once.  If the interval is
+    # truely stopped then the duration is returned, otherwise +false+.
+    def stop
+      raise Error, "Attempt to stop an interval that has not started" unless started?
+      return false if stopped?
+
+      @stop_instant = ::Hitimes.raw_instant
+
+      duration
+    end
+
+    # call-seq:
+    #     interval.duration_so_far -> Float or false
+    #
+    # return how the duration so far.  This will return the duration from the time
+    # the Interval was started if the interval is running, otherwise it will return
+    # false.
+    def duration_so_far
+      return false unless running?
+
+      raw = Hitimes.raw_instant
+      calculate_duration(@start_instant, raw)
+    end
+
+    # call-seq:
+    #    interval.started? -> boolean
+    #
+    # returns whether or not the interval has been started
+    def started?
+      !!@start_instant
+    end
+
+    # call-seq:
+    #    interval.stopped? -> boolean
+    #
+    # returns whether or not the interval has been stopped
+    def stopped?
+      !!@stop_instant
+    end
+
+    # call-seq:
+    #    interval.running? -> boolean
+    #
+    # returns whether or not the interval is running or not.  This means that it
+    # has started, but not stopped.
+    #
+    def running?
+      started? && !stopped?
+    end
+
+    # call-seq:
+    #    interval.duration -> Float
+    #    interval.to_f -> Float
+    #    interval.to_seconds -> Float
+    #    interval.length -> Float
+    #
+    # Returns the Float value of the interval, the value is in seconds.  If the
+    # interval has not had stop called yet, it will report the number of seconds
+    # in the interval up to the current point in time.
+    #
+    # Raises Error if duration is called on an interval that has not started yet.
+    #
+    def duration
+      raise Error, "Attempt to report a duration on an interval that has not started" unless started?
+
+      return duration_so_far unless stopped?
+
+      @duration = calculate_duration(@start_instant, @stop_instant) if @duration.negative?
+
+      @duration
+    end
+
+    alias to_f       duration
+    alias to_seconds duration
+    alias length     duration
+
+    private
+
+    def calculate_duration(start, stop)
+      (stop - start) / ::Hitimes::NANOSECONDS_PER_SECOND
+    end
+  end
+end