TestCoroutineDispatcher code style cleanup and todos

* Kotlin libraries code style: explicit visibility and other style-issues
* DelayController.currentTime() is val
* Using atomicfu in place of AtomicXxx classes
* Added version to ExperimentCoroutineApi annotations
* Some todos are added for future consideration
* Fixed long overflows on delay (clamp) and added test
* License headers added to files
* Tests moved to an appropriate package
* Additional ordering tests using TestBase "expect" infrastructure

Author: elizarov

binary-compatibility-validator/reference-public-api/kotlinx-coroutines-test.txt

@@ -1,50 +1,29 @@
 public abstract interface class kotlinx/coroutines/test/DelayController {
-	public abstract fun advanceTimeBy (JLjava/util/concurrent/TimeUnit;)J
-	public abstract fun advanceTimeToNextDelayed ()J
+	public abstract fun advanceTimeBy (J)J
 	public abstract fun advanceUntilIdle ()J
 	public abstract fun cleanupTestCoroutines ()V
-	public abstract fun currentTime (Ljava/util/concurrent/TimeUnit;)J
+	public abstract fun getCurrentTime ()J
 	public abstract fun pauseDispatcher ()V
 	public abstract fun pauseDispatcher (Lkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public abstract fun resumeDispatcher ()V
 	public abstract fun runCurrent ()V
 }
 
-public final class kotlinx/coroutines/test/DelayController$DefaultImpls {
-	public static synthetic fun advanceTimeBy$default (Lkotlinx/coroutines/test/DelayController;JLjava/util/concurrent/TimeUnit;ILjava/lang/Object;)J
-	public static synthetic fun currentTime$default (Lkotlinx/coroutines/test/DelayController;Ljava/util/concurrent/TimeUnit;ILjava/lang/Object;)J
-}
-
-public final class kotlinx/coroutines/test/TestBuilders {
+public final class kotlinx/coroutines/test/TestBuildersKt {
 	public static final fun runBlockingTest (Lkotlin/coroutines/CoroutineContext;Lkotlin/jvm/functions/Function2;)V
 	public static final fun runBlockingTest (Lkotlinx/coroutines/test/TestCoroutineDispatcher;Lkotlin/jvm/functions/Function2;)V
 	public static final fun runBlockingTest (Lkotlinx/coroutines/test/TestCoroutineScope;Lkotlin/jvm/functions/Function2;)V
 	public static synthetic fun runBlockingTest$default (Lkotlin/coroutines/CoroutineContext;Lkotlin/jvm/functions/Function2;ILjava/lang/Object;)V
-	public static final fun withTestContext (Lkotlinx/coroutines/test/TestCoroutineScope;Lkotlin/jvm/functions/Function2;)V
-}
-
-public final class kotlinx/coroutines/test/TestCoroutineCoroutineExceptionHandler : kotlinx/coroutines/CoroutineExceptionHandler, kotlinx/coroutines/test/UncaughtExceptionCaptor {
-	public fun <init> ()V
-	public fun cleanupTestCoroutines ()V
-	public fun fold (Ljava/lang/Object;Lkotlin/jvm/functions/Function2;)Ljava/lang/Object;
-	public fun get (Lkotlin/coroutines/CoroutineContext$Key;)Lkotlin/coroutines/CoroutineContext$Element;
-	public synthetic fun getKey ()Lkotlin/coroutines/CoroutineContext$Key;
-	public fun getKey ()Lkotlinx/coroutines/CoroutineExceptionHandler$Key;
-	public fun getUncaughtExceptions ()Ljava/util/List;
-	public fun handleException (Lkotlin/coroutines/CoroutineContext;Ljava/lang/Throwable;)V
-	public fun minusKey (Lkotlin/coroutines/CoroutineContext$Key;)Lkotlin/coroutines/CoroutineContext;
-	public fun plus (Lkotlin/coroutines/CoroutineContext;)Lkotlin/coroutines/CoroutineContext;
 }
 
 public final class kotlinx/coroutines/test/TestCoroutineDispatcher : kotlinx/coroutines/CoroutineDispatcher, kotlinx/coroutines/Delay, kotlinx/coroutines/test/DelayController {
 	public fun <init> ()V
-	public fun advanceTimeBy (JLjava/util/concurrent/TimeUnit;)J
-	public fun advanceTimeToNextDelayed ()J
+	public fun advanceTimeBy (J)J
 	public fun advanceUntilIdle ()J
 	public fun cleanupTestCoroutines ()V
-	public fun currentTime (Ljava/util/concurrent/TimeUnit;)J
 	public fun delay (JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public fun dispatch (Lkotlin/coroutines/CoroutineContext;Ljava/lang/Runnable;)V
+	public fun getCurrentTime ()J
 	public fun invokeOnTimeout (JLjava/lang/Runnable;)Lkotlinx/coroutines/DisposableHandle;
 	public fun pauseDispatcher ()V
 	public fun pauseDispatcher (Lkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
@@ -54,7 +33,15 @@ public final class kotlinx/coroutines/test/TestCoroutineDispatcher : kotlinx/cor
 	public fun toString ()Ljava/lang/String;
 }
 
+public final class kotlinx/coroutines/test/TestCoroutineExceptionHandler : kotlin/coroutines/AbstractCoroutineContextElement, kotlinx/coroutines/CoroutineExceptionHandler, kotlinx/coroutines/test/UncaughtExceptionCaptor {
+	public fun <init> ()V
+	public fun cleanupTestCoroutines ()V
+	public fun getUncaughtExceptions ()Ljava/util/List;
+	public fun handleException (Lkotlin/coroutines/CoroutineContext;Ljava/lang/Throwable;)V
+}
+
 public abstract interface class kotlinx/coroutines/test/TestCoroutineScope : kotlinx/coroutines/CoroutineScope, kotlinx/coroutines/test/DelayController, kotlinx/coroutines/test/UncaughtExceptionCaptor {
+	public abstract fun cleanupTestCoroutines ()V
 }
 
 public final class kotlinx/coroutines/test/TestCoroutineScopeKt {

kotlinx-coroutines-test/src/TestBuilders.kt

@@ -1,10 +1,11 @@
-@file:JvmName("TestBuilders")
+/*
+ * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
 
 package kotlinx.coroutines.test
 
 import kotlinx.coroutines.*
-import kotlin.coroutines.ContinuationInterceptor
-import kotlin.coroutines.CoroutineContext
+import kotlin.coroutines.*
 
 /**
  * Executes a [testBody] inside an immediate execution dispatcher.
@@ -39,8 +40,8 @@ import kotlin.coroutines.CoroutineContext
  * @param context An optional context that MUST contain a [DelayController] and/or [TestCoroutineExceptionHandler]
  * @param testBody The code of the unit-test.
  */
-@ExperimentalCoroutinesApi
-fun runBlockingTest(context: CoroutineContext? = null, testBody: suspend TestCoroutineScope.() -> Unit) {
+@ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0
+public fun runBlockingTest(context: CoroutineContext? = null, testBody: suspend TestCoroutineScope.() -> Unit) {
     val (safeContext, dispatcher) = context.checkArguments()
     // smart cast dispatcher to expose interface
     dispatcher as DelayController
@@ -69,16 +70,17 @@ private fun CoroutineContext.activeJobs(): Set<Job> {
 /**
  * Convenience method for calling [runBlockingTest] on an existing [TestCoroutineScope].
  */
-@ExperimentalCoroutinesApi
-fun TestCoroutineScope.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit) {
+// todo: need documentation on how this extension is supposed to be used
+@ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0
+public fun TestCoroutineScope.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit) {
     runBlockingTest(coroutineContext, block)
 }
 
 /**
  * Convenience method for calling [runBlockingTest] on an existing [TestCoroutineDispatcher].
  */
-@ExperimentalCoroutinesApi
-fun TestCoroutineDispatcher.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit) {
+@ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0
+public fun TestCoroutineDispatcher.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit) {
     runBlockingTest(this, block)
 }
 
@@ -103,16 +105,4 @@ private fun CoroutineContext?.checkArguments(): Pair<CoroutineContext, Continuat
 
     safeContext = safeContext + dispatcher + exceptionHandler + job
     return Pair(safeContext, dispatcher)
-}
-
-/**
- * This method is deprecated.
- *
- * @see [runBlocking]
- */
-@Deprecated("This API has been deprecated to integrate with Structured Concurrency.",
-        ReplaceWith("scope.runBlockingTest(testBody)", "kotlinx.coroutines.test"),
-        level = DeprecationLevel.ERROR)
-fun withTestContext(scope: TestCoroutineScope, testBody: suspend TestCoroutineScope.() -> Unit) {
-    scope.runBlockingTest(testBody)
 }