Add Time::Instant (#16490)

Implements [RFC 15](crystal-lang/rfcs#15)

Author: straight-shoota

spec/std/time/instant_spec.cr

@@ -0,0 +1,72 @@
+require "spec"
+
+describe "Time.instant" do
+  it "returns always increasing monotonic clock" do
+    start = Time.instant
+    loop do
+      reading = Time.instant
+      reading.should be >= start
+      break if reading > start
+    end
+  end
+end
+
+describe Time::Instant do
+  describe "#<=>" do
+    it "compares" do
+      t1 = Time.instant
+      sleep(1.nanosecond)
+      t2 = Time.instant
+
+      (t1 <=> t2).should eq(-1)
+      (t1 == t2).should be_false
+      (t1 < t2).should be_true
+    end
+  end
+
+  describe "math" do
+    it do
+      t1 = Time.instant
+
+      (t1 + 1.second - 1.second).should eq t1
+    end
+
+    it "associative" do
+      t1 = Time.instant
+      offset = 5.milliseconds
+
+      ((t1 + offset) - t1).should eq (t1 - t1) + offset
+    end
+
+    it "nanosecond precision" do
+      t1 = Time.instant
+      offset = 1.nanosecond
+
+      ((t1 + offset) - t1).should eq offset
+    end
+  end
+
+  describe "#duration_since" do
+    it "calculates" do
+      t1 = Time.instant
+      t2 = Time.instant
+      duration = t2.duration_since(t1)
+
+      (t2 - duration).should eq(t1)
+      (t1 + duration).should eq(t2)
+    end
+
+    it "saturates" do
+      t2 = Time.instant
+      t1 = t2 - 1.second
+      t1.duration_since(t2).should eq Time::Span::ZERO
+    end
+  end
+
+  describe "#elapsed" do
+    it "calculates" do
+      t1 = Time.instant - 12.microseconds
+      t1.elapsed.should be >= 12.microseconds
+    end
+  end
+end

src/time.cr

@@ -194,13 +194,13 @@ require "crystal/system/time"
 #
 # This monotonic clock should always be used for measuring elapsed time.
 #
-# A reading from this clock can be taken using `.monotonic`:
+# A reading from this clock can be taken using `.instant`:
 #
 # ```
-# t1 = Time.monotonic
+# t1 = Time.instant
 # # operation that takes 1 minute
-# t2 = Time.monotonic
-# t2 - t1 # => 1.minute (approximately)
+# t2 = Time.instant
+# t2.duration_since(t1) # => 1.minute (approximately)
 # ```
 #
 # The execution time of a block can be measured using `.measure`:

src/time/instant.cr

@@ -0,0 +1,86 @@
+# Returns the current reading of the monotonic clock.
+#
+# The execution time of a block can be measured using `.measure`.
+def Time.instant : Time::Instant
+  seconds, nanoseconds = Crystal::System::Time.monotonic
+  Time::Instant.new(seconds: seconds, nanoseconds: nanoseconds)
+end
+
+# `Time::Instant` represents a reading of a monotonic non-decreasing
+# clock for the purpose of measuring elapsed time or timing an event in the future.
+#
+# Instants are opaque values that have no public constructor or raw accessors by
+# default. They can only be obtained from the clock (`Time.instant`) and compared to one another.
+# The only useful values are differences between readings, represented as `Time::Span`.
+#
+# ## Clock properties
+#
+# Clock readings are guaranteed, barring platform bugs, to be no less than any
+# previous reading (monotonic clock).
+#
+# The measurement itself is expected to be fast (low latency) and precise within
+# nanosecond resolution. This means it might not provide the best available
+# accuracy for long-term measurements.
+#
+# The clock is not guaranteed to be steady. Ticks of the underlying clock might
+# vary in length. The clock may jump forwards or experience time dilation. But
+# it never goes backwards.
+#
+# The clock is expected to tick while the system is suspended. But this cannot be
+# guaranteed on all platforms.
+#
+# The clock is only guaranteed to apply to the current process. In practice, it is
+# usually relative to system boot, so should be interchangeable between processes.
+# But this is not guaranteed on all platforms.
+#
+# ## Example
+#
+# ```
+# start = Time.instant
+# # do something
+# elapsed = start.elapsed
+# ```
+#
+# `Time.measure(&)` is a convenient alternative for measuring elapsed time of an
+# individual code block.
+struct Time::Instant
+  include Comparable(self)
+
+  # :nodoc:
+  def initialize(@seconds : Int64, @nanoseconds : Int32)
+  end
+
+  def -(other : self) : Time::Span
+    Time::Span.new(seconds: @seconds - other.@seconds, nanoseconds: @nanoseconds - other.@nanoseconds)
+  end
+
+  def +(other : Time::Span) : self
+    span = Time::Span.new(seconds: @seconds, nanoseconds: @nanoseconds) + other
+    Instant.new(span.@seconds, span.@nanoseconds)
+  end
+
+  def -(other : Time::Span) : self
+    span = Time::Span.new(seconds: @seconds, nanoseconds: @nanoseconds) - other
+    Instant.new(span.@seconds, span.@nanoseconds)
+  end
+
+  def <=>(other : self) : Int32
+    cmp = @seconds <=> other.@seconds
+    cmp = @nanoseconds <=> other.@nanoseconds if cmp == 0
+    cmp
+  end
+
+  # Returns the duration between `other` and `self`.
+  #
+  # The resulting duration is positive or zero.
+  def duration_since(other : self) : Time::Span
+    (self - other).clamp(Time::Span.zero..)
+  end
+
+  # Returns the amount of time elapsed since `self`.
+  #
+  # The resulting duration is positive or zero.
+  def elapsed : Time::Span
+    Time.instant.duration_since(self)
+  end
+end