Rename: Clock.markNow, ClockMark.elapsedNow

Add "Now" suffix to the names of functions that depend on the current
time moment.

libraries/stdlib/js/src/kotlin/time/MonoClock.kt

@@ -23,7 +23,7 @@ public actual object MonoClock : Clock {
 
     }
 
-    override fun mark(): ClockMark = actualClock.mark()
+    override fun markNow(): ClockMark = actualClock.markNow()
 }
 
 internal external interface Process {
@@ -34,9 +34,9 @@ internal external interface Process {
 @ExperimentalTime
 internal class HrTimeClock(val process: Process) : Clock {
 
-    override fun mark(): ClockMark = object : ClockMark() {
+    override fun markNow(): ClockMark = object : ClockMark() {
         val startedAt = process.hrtime()
-        override fun elapsed(): Duration =
+        override fun elapsedNow(): Duration =
             process.hrtime(startedAt).let { (seconds, nanos) -> seconds.seconds + nanos.nanoseconds }
     }
 

libraries/stdlib/src/kotlin/time/Clock.kt

@@ -8,7 +8,7 @@ package kotlin.time
 /**
  * A source of time for measuring time intervals.
  *
- * The only operation provided by the clock is [mark]. It returns a [ClockMark], which can be used to query the elapsed time later.
+ * The only operation provided by the clock is [markNow]. It returns a [ClockMark], which can be used to query the elapsed time later.
  *
  * @see [measureTime]
  * @see [measureTimedValue]
@@ -20,22 +20,24 @@ public interface Clock {
      * Marks a time point on this clock.
      *
      * The returned [ClockMark] instance encapsulates captured time point and allows querying
-     * the duration of time interval [elapsed][ClockMark.elapsed] from that point.
+     * the duration of time interval [elapsed][ClockMark.elapsedNow] from that point.
      */
-    public fun mark(): ClockMark
+    public fun markNow(): ClockMark
 }
 
 /**
  * Represents a time point notched on a particular [Clock]. Remains bound to the clock it was taken from
- * and allows querying for the duration of time elapsed from that point (see the function [elapsed]).
+ * and allows querying for the duration of time elapsed from that point (see the function [elapsedNow]).
  */
 @SinceKotlin("1.3")
 @ExperimentalTime
 public abstract class ClockMark {
     /**
      * Returns the amount of time passed from this clock mark on the clock from which this mark was taken.
+     *
+     * Note that the value returned by this function can change on subsequent invocations.
      */
-    public abstract fun elapsed(): Duration
+    public abstract fun elapsedNow(): Duration
 
     /**
      * Returns a clock mark on the same clock that is ahead of this clock mark by the specified [duration].
@@ -54,7 +56,7 @@ public abstract class ClockMark {
 
 @ExperimentalTime
 private class AdjustedClockMark(val mark: ClockMark, val adjustment: Duration) : ClockMark() {
-    override fun elapsed(): Duration = mark.elapsed() - adjustment
+    override fun elapsedNow(): Duration = mark.elapsedNow() - adjustment
 
     override fun plus(duration: Duration): ClockMark = AdjustedClockMark(mark, adjustment + duration)
 }

libraries/stdlib/src/kotlin/time/Clocks.kt

@@ -30,11 +30,11 @@ public abstract class AbstractLongClock(protected val unit: DurationUnit) : Cloc
     protected abstract fun read(): Long
 
     private class LongClockMark(private val startedAt: Long, private val clock: AbstractLongClock, private val offset: Duration) : ClockMark() {
-        override fun elapsed(): Duration = (clock.read() - startedAt).toDuration(clock.unit) - offset
+        override fun elapsedNow(): Duration = (clock.read() - startedAt).toDuration(clock.unit) - offset
         override fun plus(duration: Duration): ClockMark = LongClockMark(startedAt, clock, offset + duration)
     }
 
-    override fun mark(): ClockMark = LongClockMark(read(), this, Duration.ZERO)
+    override fun markNow(): ClockMark = LongClockMark(read(), this, Duration.ZERO)
 }
 
 /**
@@ -52,11 +52,11 @@ public abstract class AbstractDoubleClock(protected val unit: DurationUnit) : Cl
     protected abstract fun read(): Double
 
     private class DoubleClockMark(private val startedAt: Double, private val clock: AbstractDoubleClock, private val offset: Duration) : ClockMark() {
-        override fun elapsed(): Duration = (clock.read() - startedAt).toDuration(clock.unit) - offset
+        override fun elapsedNow(): Duration = (clock.read() - startedAt).toDuration(clock.unit) - offset
         override fun plus(duration: Duration): ClockMark = DoubleClockMark(startedAt, clock, offset + duration)
     }
 
-    override fun mark(): ClockMark = DoubleClockMark(read(), this, Duration.ZERO)
+    override fun markNow(): ClockMark = DoubleClockMark(read(), this, Duration.ZERO)
 }
 
 /**

libraries/stdlib/src/kotlin/time/measureTime.kt

@@ -34,9 +34,9 @@ public inline fun Clock.measureTime(block: () -> Unit): Duration {
         callsInPlace(block, InvocationKind.EXACTLY_ONCE)
     }
 
-    val mark = mark()
+    val mark = markNow()
     block()
-    return mark.elapsed()
+    return mark.elapsedNow()
 }
 
 
@@ -79,7 +79,7 @@ public inline fun <T> Clock.measureTimedValue(block: () -> T): TimedValue<T> {
         callsInPlace(block, InvocationKind.EXACTLY_ONCE)
     }
 
-    val mark = mark()
+    val mark = markNow()
     val result = block()
-    return TimedValue(result, mark.elapsed())
+    return TimedValue(result, mark.elapsedNow())
 }

libraries/stdlib/test/time/ClockMarkTest.kt

@@ -14,7 +14,7 @@ class ClockMarkTest {
     fun adjustment() {
         val clock = TestClock()
 
-        val mark = clock.mark()
+        val mark = clock.markNow()
         val markFuture1 = mark + 1.milliseconds
         val markFuture2 = mark - (-1).milliseconds
 
@@ -23,15 +23,15 @@ class ClockMarkTest {
 
         clock += 500_000.nanoseconds
 
-        val elapsed = mark.elapsed()
+        val elapsed = mark.elapsedNow()
         val elapsedFromFuture = elapsed - 1.milliseconds
         val elapsedFromPast = elapsed + 1.milliseconds
 
         assertEquals(0.5.milliseconds, elapsed)
-        assertEquals(elapsedFromFuture, markFuture1.elapsed())
+        assertEquals(elapsedFromFuture, markFuture1.elapsedNow())
-        assertEquals(elapsedFromFuture, markFuture2.elapsed())
+        assertEquals(elapsedFromFuture, markFuture2.elapsedNow())
 
-        assertEquals(elapsedFromPast, markPast1.elapsed())
+        assertEquals(elapsedFromPast, markPast1.elapsedNow())
-        assertEquals(elapsedFromPast, markPast2.elapsed())
+        assertEquals(elapsedFromPast, markPast2.elapsedNow())
     }
 }

libraries/stdlib/test/time/TestClockTest.kt

@@ -48,15 +48,15 @@ class TestClockTest {
     @Test
     fun nanosecondRounding() {
         val clock = TestClock()
-        val mark = clock.mark()
+        val mark = clock.markNow()
 
         repeat(10_000) {
             clock += 0.9.nanoseconds
 
-            assertEquals(Duration.ZERO, mark.elapsed())
+            assertEquals(Duration.ZERO, mark.elapsedNow())
         }
 
         clock += 1.9.nanoseconds
-        assertEquals(1.nanoseconds, mark.elapsed())
+        assertEquals(1.nanoseconds, mark.elapsedNow())
     }
 }

libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt

@@ -5270,24 +5270,24 @@ public final class kotlin/text/UStringsKt {
 public abstract class kotlin/time/AbstractDoubleClock : kotlin/time/Clock {
 	public fun <init> (Ljava/util/concurrent/TimeUnit;)V
 	protected final fun getUnit ()Ljava/util/concurrent/TimeUnit;
-	public fun mark ()Lkotlin/time/ClockMark;
+	public fun markNow ()Lkotlin/time/ClockMark;
 	protected abstract fun read ()D
 }
 
 public abstract class kotlin/time/AbstractLongClock : kotlin/time/Clock {
 	public fun <init> (Ljava/util/concurrent/TimeUnit;)V
 	protected final fun getUnit ()Ljava/util/concurrent/TimeUnit;
-	public fun mark ()Lkotlin/time/ClockMark;
+	public fun markNow ()Lkotlin/time/ClockMark;
 	protected abstract fun read ()J
 }
 
 public abstract interface class kotlin/time/Clock {
-	public abstract fun mark ()Lkotlin/time/ClockMark;
+	public abstract fun markNow ()Lkotlin/time/ClockMark;
 }
 
 public abstract class kotlin/time/ClockMark {
 	public fun <init> ()V
-	public abstract fun elapsed ()D
+	public abstract fun elapsedNow ()D
 	public fun minus-LRDsOJo (D)Lkotlin/time/ClockMark;
 	public fun plus-LRDsOJo (D)Lkotlin/time/ClockMark;
 }