Duration and time measurement API

[ilya-g]

This issue is to discuss the proposal to introduce Duration, TimeSource, TimeMark and time measurement API.

[joffrey-bion]

The IDE should only show the completions when the import is there

I kinda disagree here. In Kotlin, a lot of things are extensions from other packages, and I rely a LOT on being able to auto-complete and auto-import from packages that I haven't imported yet. This would be quite a big inconvenience (at least to me) if only imported stuff were auto-completed.

[RafaelKr]

The IDE should only show the completions when the import is there

I kinda disagree here. In Kotlin, a lot of things are extensions from other packages, and I rely a LOT on being able to auto-complete and auto-import from packages that I haven't imported yet. This would be quite a big inconvenience (at least to me) if only imported stuff were auto-completed.

valid point.

[ilya-g]

During the pre-stabilization review of the Duration class, we've decided to make the DurationUnit enum not a type alias of java.util.concurrent.TimeUnit on JVM, but a standalone enum. We haven't found convincing cases where having DurationUnit === TimeUnit would make much sense, and on the other hand, TimeUnit API exposed through a type alias could be very confusing for DurationUnit users.

[PaulWoitaschek]

PSA: it seems the extensions have been moved to the companion object and the previously new ones were deprecated in 1.6

https://github.com/JetBrains/kotlin/commit/9cbbc3519dab4cc3febfcfdcdf91b087bda98147#diff-a192d12cd63b9223cbb5ee2c2aadf51aa0e07cbdc057346f87643703a3984121

[joffrey-bion]

Wait, so Duration.seconds() and other factory functions were deprecated now? How come?

I thought the whole point was to provide extension properties for literal numbers and factory functions for variables.

The initial point that drove the change from extension properties to factory functions was that someVarMillis.milliseconds reads kinda weird and this still applies... Duration.milliseconds(someVarMillis) is clearer in this case IMO. But for literals 200.milliseconds is really nicer than using the factory function.

[ilya-g]

Wait, so Duration.seconds() and other factory functions were deprecated now? How come?

@joffrey-bion We thought that having both would be an overkill and bloat the API surface. I'd propose using .toDuration(DurationUnit.MILLISECONDS) if you want to avoid tautology of millis.milliseconds.

[ilya-g]

This PR updates the proposal text to include a section about value class-based time marks returned by the default monotonic time source: #310

This change of the TimeSource.Monotonic is intended to shave the allocation costs of a time mark when it's taken from that default time source. The change to the experimental kotlin.time API was made available in Kotlin 1.7.0.

[pocmo]

I would like to ask about serialization. The KEEP says:

A TimeMark is not serializable because it isn't possible to restore the captured time point upon deserialization in a meaningful way.

This kind of makes sense to me - since this may depend on the TimeSource being used. If, on Android, [SystemClock.elapsedRealtimeNanos](https://developer.android.com/reference/android/os/SystemClock.html#elapsedRealtimeNanos()) is used then deserializing a value after device reboot may not create a meaningful TimeMark.

I wonder how to deal with situations where serialization is needed. Especially on Android again, where an app process may get killed and recreated while the app is in the background. Without serialization there may be no way to keep a TimeMark if that happens?

[ilya-g]

The proposal is updated with the description of comparable time marks introduced in Kotlin 1.8.0 in the experimental part of kotlin.time API: #353

We're considering to stabilize the most of the remaining experimental API in kotlin.time in Kotlin 1.9.0, including time sources, time marks, and measureTime* functions. Please use this chance to review the proposal once again and maybe give some final feedback, we'd appreciate it.