Merge branch 'develop': release 1.4

Author: frost13it

README.md

@@ -39,6 +39,19 @@ kinfra-commons
 
 Аналог `Instant` на основе `System.nanoTime()` для измерения прошедшего времени.
 
+#### Класс Deadline
+
+Предназначен для передачи в вызываемый код информации о том, когда истечёт таймаут его выполнения.
+
+Для корректной работы этого механизма необходимо использовать функцию `withDeadlineAfter()` вместо `withTimeout()`.
+
+Пример использования:
+
+    withDeadlineAfter(Duration.ofSeconds(10)) {
+        ....
+        println("Time left: " + coroutineContext[Deadline]?.timeLeft())
+    }
+
 #### Класс TimeTicks
 
 Представляет время в тиках (100 наносекунд)
@@ -78,10 +91,9 @@ kinfra-commons
  * `ByteArray.toHexString()` и `byteArrayOfHex()`
  * `StringBuilder.appendHexByte()`
 
-### Either
+### Either<L, R>
 
-Библиотека предоставляет класс Either для представления выбора между ошибочным состоянием
-и успешным получением результата.
+Представляет выбор между ошибочным состоянием (L) и успешным получением результата (R).
 
 Сборка
 ------

build.gradle

@@ -4,10 +4,11 @@ plugins {
 }
 
 ext {
-    release = '1.3.1'
+    release = '1.4'
 
     versions = [
         assertj: '3.14.0',
+        coroutines: '1.3.3',
     ]
 
     branch = project.properties["branch"]?.toString()
@@ -21,5 +22,9 @@ version = ext.version
 sourceCompatibility = 8
 
 dependencies {
+    allMain platform("org.jetbrains.kotlinx:kotlinx-coroutines-bom:${versions.coroutines}")
+
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-jdk8"
+
     testImplementation "org.assertj:assertj-core:${versions.assertj}"
 }

src/main/kotlin/ru/kontur/kinfra/commons/Either.kt

@@ -30,9 +30,6 @@ sealed class Either<out L, out R> {
 
         fun <L> left(error: L): Either<L, Nothing> = Left(error)
 
-        @Deprecated(level = DeprecationLevel.ERROR, message = "Don't use Either for exceptions")
-        fun <E> left(error: E): Either<E, Nothing> where E : Throwable = Left(error)
-
         fun <R> right(value: R): Either<Nothing, R> = Right(value)
 
     }

src/main/kotlin/ru/kontur/kinfra/commons/time/Deadline.kt

@@ -0,0 +1,123 @@
+package ru.kontur.kinfra.commons.time
+
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.TimeoutCancellationException
+import kotlinx.coroutines.time.withTimeout
+import kotlinx.coroutines.withContext
+import ru.kontur.kinfra.commons.time.MonotonicInstant.Companion.now
+import java.time.Duration
+import java.time.temporal.ChronoUnit
+import kotlin.coroutines.CoroutineContext
+import kotlin.coroutines.coroutineContext
+
+/**
+ * Represents a moment of time when a coroutine's timeout will expire.
+ *
+ * Purpose of this class is to inform a code running in a coroutine on the time when it should complete its execution.
+ *
+ * For this to work [withDeadlineAfter] should be used instead of [withTimeout] across the entire codebase.
+ *
+ * **Warning**: don't use `withContext(deadline)`, as it does not setup timeout
+ * and unconditionally replaces current deadline with a given one.
+ * Always use `withDeadline()` instead.
+ *
+ * Usage:
+ *
+ *   1. Run with timeout:
+ *      ```
+ *      withDeadlineAfter(Duration.ofSeconds(10)) {
+ *          ....
+ *          println("Time left: " + coroutineContext[Deadline]?.timeLeft())
+ *      }
+ *      ```
+ *
+ *   2. Run with a specified deadline:
+ *      ```
+ *      val deadline = ...
+ *      withDeadline(deadline) {
+ *          ...
+ *      }
+ *      ```
+ */
+class Deadline private constructor(
+    private val time: MonotonicInstant
+) : CoroutineContext.Element, Comparable<Deadline> {
+
+    fun isPassed(): Boolean = timeLeft() <= Duration.ZERO
+
+    /**
+     * Returns an amount of time before this deadline will [pass][isPassed].
+     *
+     * Negative values represent the time elapsed since this deadline is passed.
+     */
+    fun timeLeft(): Duration {
+        // Result is truncated because withTimeout's precision is a millisecond
+        return (time - now()).truncatedTo(ChronoUnit.MILLIS)
+    }
+
+    operator fun plus(offset: Duration) = Deadline(time + offset)
+
+    operator fun minus(offset: Duration) = Deadline(time - offset)
+
+    override fun compareTo(other: Deadline): Int {
+        return time.compareTo(other.time)
+    }
+
+    override val key: CoroutineContext.Key<*>
+        get() = Deadline
+
+    override fun equals(other: Any?): Boolean {
+        return other is Deadline && other.time == this.time
+    }
+
+    override fun hashCode(): Int {
+        return time.hashCode()
+    }
+
+    override fun toString(): String {
+        return "Deadline($time)"
+    }
+
+    companion object : CoroutineContext.Key<Deadline> {
+
+        /**
+         * Returns a [Deadline] that passes after given [timeout] from now.
+         *
+         * The timeout **must** be positive.
+         */
+        fun after(timeout: Duration): Deadline {
+            require(timeout > Duration.ZERO) { "Timeout must be positive: $timeout" }
+            return Deadline(now() + timeout)
+        }
+
+    }
+
+}
+
+/**
+ * Runs a given suspending [block] of code inside a coroutine with a specified [deadline][Deadline]
+ * and throws a [TimeoutCancellationException] when the deadline passes.
+ *
+ * If current deadline is less than the specified one, it will be used instead.
+ */
+suspend fun <R> withDeadline(deadline: Deadline, block: suspend CoroutineScope.() -> R): R {
+    val currentDeadline = coroutineContext[Deadline]
+    val newDeadline = currentDeadline
+        ?.let { minOf(it, deadline) }
+        ?: deadline
+
+    return withTimeout(newDeadline.timeLeft()) {
+        withContext(newDeadline, block)
+    }
+}
+
+/**
+ * Shortcut for `withDeadline(Deadline.after(duration))`.
+ *
+ * @see withDeadline
+ * @see Deadline.after
+ */
+suspend fun <R> withDeadlineAfter(timeout: Duration, block: suspend CoroutineScope.() -> R): R {
+    val deadline = Deadline.after(timeout)
+    return withDeadline(deadline, block)
+}

src/main/kotlin/ru/kontur/kinfra/commons/time/MonotonicInstant.kt

@@ -11,38 +11,49 @@ import kotlin.time.*
  * To be replaced by [ClockMark] of [MonoClock] after its final release.
  */
 class MonotonicInstant private constructor(
-    private val nanos: Long
+    private val nanoOffset: Long
 ) : Comparable<MonotonicInstant> {
     // todo: deprecate after release of kotlin.time
 
     operator fun plus(duration: Duration): MonotonicInstant {
-        return MonotonicInstant(nanos + duration.toNanos())
+        return MonotonicInstant(nanoOffset + duration.toNanos())
     }
 
     operator fun minus(duration: Duration): MonotonicInstant {
-        return MonotonicInstant(nanos - duration.toNanos())
+        return MonotonicInstant(nanoOffset - duration.toNanos())
     }
 
     operator fun minus(other: MonotonicInstant): Duration {
-        return Duration.ofNanos(nanos - other.nanos)
+        return Duration.ofNanos(nanoOffset - other.nanoOffset)
     }
 
     override fun compareTo(other: MonotonicInstant): Int {
-        return (nanos - other.nanos).compareTo(0)
+        // implies that nanoOffset is monotonic
+        return nanoOffset.compareTo(other.nanoOffset)
     }
 
     override fun equals(other: Any?): Boolean {
-        return other is MonotonicInstant && nanos == other.nanos
+        return other is MonotonicInstant && nanoOffset == other.nanoOffset
     }
 
     override fun hashCode(): Int {
-        return nanos.hashCode()
+        return nanoOffset.hashCode()
+    }
+
+    override fun toString(): String {
+        return "MonotonicInstant(${Duration.ofSeconds(0, nanoOffset)} since origin)"
     }
 
     companion object {
 
+        private val ORIGIN_NANOS = rawNow()
+
         fun now(): MonotonicInstant {
-            return MonotonicInstant(System.nanoTime())
+            return MonotonicInstant(rawNow() - ORIGIN_NANOS)
+        }
+
+        private fun rawNow(): Long {
+            return System.nanoTime()
         }
 
     }

src/test/kotlin/ru/kontur/kinfra/commons/time/DeadlineTest.kt

@@ -0,0 +1,91 @@
+package ru.kontur.kinfra.commons.time
+
+import kotlinx.coroutines.runBlocking
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertThrows
+import java.time.Duration
+
+class DeadlineTest {
+
+    @Test
+    fun plus_minus() {
+        val duration = Duration.ofSeconds(1)
+        val sample = Deadline.after(duration)
+        val earlier = sample - duration
+        val later = sample + duration
+
+        assertThat(earlier).isLessThan(sample)
+        assertThat(later).isGreaterThan(sample)
+        assertThat(earlier + duration.multipliedBy(2)).isEqualTo(later)
+    }
+
+    @Test
+    fun is_passed_nanosecond() {
+        val deadline = Deadline.after(Duration.ofNanos(1))
+        assertThat(deadline).matches { it.isPassed() }
+    }
+
+    @Test
+    fun is_passed_second() {
+        val deadline = Deadline.after(Duration.ofSeconds(1))
+        assertThat(deadline).matches { !it.isPassed() }
+    }
+
+    @Test
+    fun withDeadline_use_earlier() = runBlocking<Unit> {
+        val earlier = Deadline.after(Duration.ofSeconds(1))
+        val later = Deadline.after(Duration.ofSeconds(2))
+
+        withDeadline(earlier) {
+            withDeadline(later) {
+                assertThat(coroutineContext[Deadline]).isEqualTo(earlier)
+            }
+        }
+
+        withDeadline(later) {
+            withDeadline(earlier) {
+                assertThat(coroutineContext[Deadline]).isEqualTo(earlier)
+            }
+        }
+    }
+
+    @Test
+    fun time_left_instantly() {
+        val timeout = Duration.ofSeconds(1)
+        val deadline = Deadline.after(timeout)
+        val timeLeft = deadline.timeLeft()
+        val maxDifference = Duration.ofMillis(20)
+
+        assertThat(timeLeft).isLessThanOrEqualTo(timeout)
+        assertThat(timeLeft).isGreaterThan(timeout - maxDifference)
+    }
+
+    @Test
+    fun time_left_after_delay() {
+        val timeout = Duration.ofSeconds(1)
+        val deadline = Deadline.after(timeout)
+
+        val delay = Duration.ofMillis(50)
+        Thread.sleep(delay.toMillis())
+        val timeLeft = deadline.timeLeft()
+
+        assertThat(timeLeft).isLessThanOrEqualTo(timeout - delay)
+        assertThat(timeLeft).isGreaterThan(timeout - delay.multipliedBy(2))
+    }
+
+    @Test
+    fun zero_timeout_forbidden() {
+        assertThrows<IllegalArgumentException> {
+            Deadline.after(Duration.ZERO)
+        }
+    }
+
+    @Test
+    fun negative_timeout_forbidden() {
+        assertThrows<IllegalArgumentException> {
+            Deadline.after(Duration.ofSeconds(1).negated())
+        }
+    }
+
+}