Move Instant and Clock from kotlinx-datetime to stdlib #KT-72480

Author: Abduqodiri Qurbonzoda

kotlin-native/runtime/src/main/cpp/Porting.cpp

@@ -273,6 +273,10 @@ uint64_t getTimeMicros() {
   return duration_cast<microseconds>(steady_time_clock::now().time_since_epoch()).count();
 }
 
+uint64_t getSystemTimeNanos() {
+  return duration_cast<nanoseconds>(system_clock::now().time_since_epoch()).count();
+}
+
 bool isLittleEndian() {
   return __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__;
 }

kotlin-native/runtime/src/main/cpp/Porting.h

@@ -45,6 +45,7 @@ uintptr_t currentThreadId();
 uint64_t getTimeMillis();
 uint64_t getTimeMicros();
 uint64_t getTimeNanos();
+uint64_t getSystemTimeNanos();
 
 // Endianness
 bool isLittleEndian();

kotlin-native/runtime/src/main/cpp/Time.cpp

@@ -20,16 +20,20 @@
 
 extern "C" {
 
-KLong Kotlin_system_getTimeMillis() {
+KLong Kotlin_system_getSteadyTimeMillis() {
   return konan::getTimeMillis();
 }
 
-KLong Kotlin_system_getTimeNanos() {
+KLong Kotlin_system_getSteadyTimeNanos() {
   return konan::getTimeNanos();
 }
 
-KLong Kotlin_system_getTimeMicros() {
+KLong Kotlin_system_getSteadyTimeMicros() {
   return konan::getTimeMicros();
 }
 
+KLong Kotlin_system_getSystemTimeNanos() {
+  return konan::getSystemTimeNanos();
+}
+
 }  // extern "C"

kotlin-native/runtime/src/main/kotlin/kotlin/system/Timing.kt

@@ -22,7 +22,7 @@ import kotlin.time.*
  */
 @Deprecated("Use measureTime() or TimeSource.Monotonic.markNow() instead.")
 @DeprecatedSinceKotlin(warningSince = "1.9", errorSince = "2.1")
-@GCUnsafeCall("Kotlin_system_getTimeMillis")
+@GCUnsafeCall("Kotlin_system_getSteadyTimeMillis")
 public external fun getTimeMillis() : Long
 
 /**
@@ -39,7 +39,7 @@ public external fun getTimeMillis() : Long
  */
 @Deprecated("Use measureTime() or TimeSource.Monotonic.markNow() instead.")
 @DeprecatedSinceKotlin(warningSince = "1.9", errorSince = "2.1")
-@GCUnsafeCall("Kotlin_system_getTimeNanos")
+@GCUnsafeCall("Kotlin_system_getSteadyTimeNanos")
 public external fun getTimeNanos() : Long
 
 /**
@@ -56,7 +56,7 @@ public external fun getTimeNanos() : Long
  */
 @Deprecated("Use measureTime() or TimeSource.Monotonic.markNow() instead.")
 @DeprecatedSinceKotlin(warningSince = "1.9", errorSince = "2.1")
-@GCUnsafeCall("Kotlin_system_getTimeMicros")
+@GCUnsafeCall("Kotlin_system_getSteadyTimeMicros")
 public external fun getTimeMicros() : Long
 
 /**

kotlin-native/runtime/src/main/kotlin/kotlin/time/InstantNative.kt

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.time
+
+import kotlin.native.internal.GCUnsafeCall
+
+@ExperimentalTime
+internal actual fun systemClockNow(): Instant = getSystemTimeNanos().let { time ->
+    // Instant.MAX and Instant.MIN are never going to be exceeded using just the Long number of nanoseconds
+    Instant(time.floorDiv(NANOS_PER_SECOND.toLong()), time.mod(NANOS_PER_SECOND.toLong()).toInt())
+}
+
+@GCUnsafeCall("Kotlin_system_getSystemTimeNanos")
+private external fun getSystemTimeNanos(): Long
+
+@ExperimentalTime
+internal actual fun serializedInstant(instant: Instant): Any =
+    throw UnsupportedOperationException("Serialization is supported only in Kotlin/JVM")

libraries/stdlib/build.gradle.kts

@@ -77,6 +77,7 @@ val commonTestOptIns = listOf(
     "kotlin.ExperimentalStdlibApi",
     "kotlin.io.encoding.ExperimentalEncodingApi",
     "kotlin.uuid.ExperimentalUuidApi",
+    "kotlin.time.ExperimentalTime",
 )
 
 kotlin {

libraries/stdlib/jdk8/src/kotlin/internal/jdk8/JDK8PlatformImplementations.kt

@@ -19,10 +19,10 @@ package kotlin.internal.jdk8
 
 import java.util.regex.MatchResult
 import java.util.regex.Matcher
-import kotlin.internal.PlatformImplementations
 import kotlin.internal.jdk7.JDK7PlatformImplementations
 import kotlin.random.Random
 import kotlin.random.jdk8.PlatformThreadLocalRandom
+import kotlin.time.*
 
 internal open class JDK8PlatformImplementations : JDK7PlatformImplementations() {
 
@@ -57,4 +57,19 @@ internal open class JDK8PlatformImplementations : JDK7PlatformImplementations()
         // then.
         if (sdkIsNullOrAtLeast(34)) PlatformThreadLocalRandom() else super.defaultPlatformRandom()
 
+    @ExperimentalTime
+    override fun getSystemClock(): Clock {
+        // java.time.Instant is available since SDK 26
+        return if (sdkIsNullOrAtLeast(26)) object : Clock {
+            override fun now(): Instant =
+                java.time.Instant.now().toKotlinInstant()
+        } else object : Clock {
+            override fun now(): Instant =
+                // After experimenting in Android Studio, it seems like on Android with API < 26, only millisecond precision
+                // is available in `Instant.now()` with core library desugaring enabled. Because of that, `currentTimeMillis`
+                // is good enough + suggesting that our users enable core library desugaring isn't going to bring any benefits,
+                // so the KDoc for [Clock] does not mention any of this.
+                Instant.fromEpochMilliseconds(System.currentTimeMillis())
+        }
+    }
 }

libraries/stdlib/jdk8/src/kotlin/time/InstantConversions.kt

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+@file:JvmName("InstantConversionsJDK8Kt")
+@file:JvmPackageName("kotlin.time.jdk8")
+
+package kotlin.time
+
+
+/**
+ * Converts this [kotlin.time.Instant][Instant] value to a [java.time.Instant][java.time.Instant] value.
+ *
+ * @sample samples.time.Instants.toJavaInstant
+ */
+@SinceKotlin("2.1")
+@ExperimentalTime
+public fun Instant.toJavaInstant(): java.time.Instant =
+    java.time.Instant.ofEpochSecond(epochSeconds, nanosecondsOfSecond.toLong())
+
+/**
+ * Converts this [java.time.Instant][java.time.Instant] value to a [kotlin.time.Instant][Instant] value.
+ *
+ * @sample samples.time.Instants.toKotlinInstant
+ */
+@SinceKotlin("2.1")
+@ExperimentalTime
+public fun java.time.Instant.toKotlinInstant(): Instant =
+    Instant.fromEpochSeconds(epochSecond, nano)

libraries/stdlib/jdk8/test/time/InstantConversionTest.kt

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.jdk8.time.test
+
+import kotlin.time.*
+import kotlin.test.*
+import kotlin.random.*
+import java.time.Instant as JTInstant
+
+class InstantConversionTest {
+    @Test
+    fun instant() {
+        fun test(seconds: Long, nanosecond: Int) {
+            val ktInstant = Instant.fromEpochSeconds(seconds, nanosecond.toLong())
+            val jtInstant = JTInstant.ofEpochSecond(seconds, nanosecond.toLong())
+
+            assertEquals(ktInstant, jtInstant.toKotlinInstant())
+            assertEquals(jtInstant, ktInstant.toJavaInstant())
+
+            assertEquals(ktInstant, jtInstant.toString().let(Instant::parse))
+            assertEquals(jtInstant, ktInstant.toString().let(JTInstant::parse))
+        }
+
+        repeat(100) {
+            val seconds = Random.nextLong(1_000_000_000_000)
+            val nanos = Random.nextInt()
+            test(seconds, nanos)
+        }
+    }
+}

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

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.time
+
+import kotlin.js.Date
+
+/**
+ * Converts the [Instant] to an instance of JS [Date].
+ *
+ * The conversion is lossy: JS uses millisecond precision to represent dates, and [Instant] allows for nanosecond
+ * resolution.
+ */
+@SinceKotlin("2.1")
+@ExperimentalTime
+public fun Instant.toJSDate(): Date = Date(milliseconds = toEpochMilliseconds().toDouble())
+
+/**
+ * Converts the JS [Date] to the corresponding [Instant].
+ */
+@SinceKotlin("2.1")
+@ExperimentalTime
+public fun Date.toKotlinInstant(): Instant = Instant.fromEpochMilliseconds(getTime().toLong())

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

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.time
+
+import kotlin.js.Date
+
+@ExperimentalTime
+internal actual fun systemClockNow(): Instant =
+    Instant.fromEpochMilliseconds(Date().getTime().toLong())
+
+@ExperimentalTime
+internal actual fun serializedInstant(instant: Instant): Any =
+    throw UnsupportedOperationException("Serialization is supported only in Kotlin/JVM")

libraries/stdlib/js/test/time/InstantConversionTest.kt

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package test.time
+
+import kotlin.js.Date
+import kotlin.test.*
+import kotlin.time.*
+
+class InstantConversionTest {
+    @Test
+    fun toJSDateTest() {
+        val releaseInstant = Instant.parse("2016-02-15T00:00:00Z")
+        val releaseDate = releaseInstant.toJSDate()
+        assertEquals(2016, releaseDate.getUTCFullYear())
+        assertEquals(1, releaseDate.getUTCMonth())
+        assertEquals(15, releaseDate.getUTCDate())
+    }
+
+    @Test
+    fun toInstantTest() {
+        val kotlinReleaseEpochMilliseconds = 1455494400000
+        val releaseDate = Date(milliseconds = kotlinReleaseEpochMilliseconds)
+        val releaseInstant = Instant.parse("2016-02-15T00:00:00Z")
+        assertEquals(releaseInstant, releaseDate.toKotlinInstant())
+    }
+}

libraries/stdlib/jvm/src/kotlin/internal/PlatformImplementations.kt

@@ -9,6 +9,8 @@ import java.lang.reflect.Method
 import java.util.regex.MatchResult
 import kotlin.random.FallbackThreadLocalRandom
 import kotlin.random.Random
+import kotlin.time.Clock
+import kotlin.time.ExperimentalTime
 
 internal open class PlatformImplementations {
 
@@ -43,6 +45,11 @@ internal open class PlatformImplementations {
     }
 
     public open fun defaultPlatformRandom(): Random = FallbackThreadLocalRandom()
+
+    @ExperimentalTime
+    public open fun getSystemClock(): Clock {
+        throw UnsupportedOperationException("getSystemClock should not be called on the base PlatformImplementations.")
+    }
 }
 
 

libraries/stdlib/jvm/src/kotlin/time/InstantJvm.kt

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.time
+
+import java.io.*
+import kotlin.internal.IMPLEMENTATIONS
+
+@ExperimentalTime
+private val systemClock: Clock = IMPLEMENTATIONS.getSystemClock()
+
+@ExperimentalTime
+internal actual fun systemClockNow(): Instant = systemClock.now()
+
+@ExperimentalTime
+private class InstantSerialized(
+    var epochSeconds: Long,
+    var nanosecondsOfSecond: Int
+) : Externalizable {
+
+    constructor() : this(0L, 0) // for deserialization
+
+    override fun writeExternal(output: ObjectOutput) {
+        output.writeLong(epochSeconds)
+        output.writeInt(nanosecondsOfSecond)
+    }
+
+    override fun readExternal(input: ObjectInput) {
+        epochSeconds = input.readLong()
+        nanosecondsOfSecond = input.readInt()
+    }
+
+    private fun readResolve(): Any =
+        Instant.fromEpochSeconds(epochSeconds, nanosecondsOfSecond)
+
+    companion object {
+        private const val serialVersionUID: Long = 0L
+    }
+}
+
+@ExperimentalTime
+internal actual fun serializedInstant(instant: Instant): Any =
+    InstantSerialized(instant.epochSeconds, instant.nanosecondsOfSecond)

libraries/stdlib/jvm/test/time/InstantJVMTest.kt

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package test.time
+
+import test.io.serializeAndDeserialize
+import kotlin.test.*
+import kotlin.time.Instant
+
+class InstantJVMTest {
+    @Test
+    fun serialize() {
+        listOf(
+            Instant.MIN,
+            Instant.MAX,
+            Instant.DISTANT_PAST,
+            Instant.DISTANT_FUTURE,
+            Instant.fromEpochSeconds(0),
+            Instant.fromEpochSeconds(1, 1),
+            Instant.fromEpochSeconds(-1, 1),
+        ).forEach {
+            assertEquals(it, serializeAndDeserialize(it))
+        }
+    }
+}

libraries/stdlib/samples/build.gradle

@@ -14,6 +14,7 @@ compileTestKotlin {
         optIn.addAll([
                 "kotlin.ExperimentalStdlibApi",
                 "kotlin.ExperimentalUnsignedTypes",
+                "kotlin.time.ExperimentalTime",
         ])
     }
 }