Attempt to fix a flaky coroutine-dump-verifying test (#4589)

Fixes #4418
(unless it keeps happening)

This problem couldn't be reproduced locally, to this fix is purely
analytical.

The problematic test attempts to launch a coroutine then await
until the coroutine suspends.
The way it was doing that before the change is:
- Hold a monitor and `wait` on the test body side;
- Acquire a monitor and `notify` on the coroutine side
  *right before* the suspension point;
- On the test body side, wait for the coroutine thread to enter the
  `TIMED_WAIT` state, indicating that its scheduler worker
  has finished its piece of work and now waits for new commands,
  which must mean the suspension point was reached.

The problem is that thread states are not synchronization
primitives, and no happens-before is established between the
code a thread executes before the state change and the code right
after the state change is observed.

With this change, we establish a complete happens-before chain:
- The test body wakes up after it's `resume`d as a coroutine.
- `complete` on a latch happens-before the `resume`.
- The suspension happens-before the `complete`,
  as suspension and the `complete` are done in the same thread.

With no way to verify the fix, it's unclear if that was
the problem, so we can only hope the change helps.

Author: dkhalanskyjb

kotlinx-coroutines-debug/test/CoroutinesDumpTest.kt

@@ -2,28 +2,27 @@ package kotlinx.coroutines.debug
 
 import kotlinx.coroutines.testing.*
 import kotlinx.coroutines.*
-import org.junit.*
-import org.junit.Test
-import kotlin.coroutines.*
 import kotlin.test.*
 
 class CoroutinesDumpTest : DebugTestBase() {
     private val monitor = Any()
     private var coroutineThread: Thread? = null // guarded by monitor
 
-    @Before
+    @BeforeTest
     override fun setUp() {
         super.setUp()
         DebugProbes.enableCreationStackTraces = true
     }
 
     @Test
     fun testSuspendedCoroutine() = runBlocking {
-        val deferred = async(Dispatchers.Default) {
-            sleepingOuterMethod()
+        val latch = CompletableDeferred<Unit>()
+        val singleThreadedDispatcher = newSingleThreadContext("TestCoroutineThread")
+        val deferred = async(singleThreadedDispatcher) {
+            sleepingOuterMethod(singleThreadedDispatcher, latch)
         }
 
-        awaitCoroutine()
+        latch.await()
         val found = DebugProbes.dumpCoroutinesInfo().single { it.job === deferred }
         verifyDump(
             "Coroutine \"coroutine#1\":DeferredCoroutine{Active}@1e4a7dd4, state: SUSPENDED\n" +
@@ -35,6 +34,7 @@ class CoroutinesDumpTest : DebugTestBase() {
                     "\tat kotlinx.coroutines.CoroutineStart.invoke(CoroutineStart.kt)\n",
             ignoredCoroutine = "BlockingCoroutine"
         ) {
+            singleThreadedDispatcher.close()
             deferred.cancel()
             coroutineThread!!.interrupt()
         }
@@ -181,29 +181,39 @@ class CoroutinesDumpTest : DebugTestBase() {
     private suspend fun nestedActiveMethod(shouldSuspend: Boolean) {
         if (shouldSuspend) yield()
         notifyCoroutineStarted()
-        while (coroutineContext[Job]!!.isActive) {
+        while (currentCoroutineContext()[Job]!!.isActive) {
             try {
                 Thread.sleep(60_000)
             } catch (_ : InterruptedException) {
             }
         }
     }
 
-    private suspend fun sleepingOuterMethod() {
-        sleepingNestedMethod()
-        yield() // TCE
+    private suspend fun sleepingOuterMethod(currentDispatcher: CoroutineDispatcher, latch: CompletableDeferred<Unit>) {
+        sleepingNestedMethod(currentDispatcher, latch)
+        yield() // TCE: make sure `sleepingOuterMethod` is contained in the continuation of `sleepingNestedMethod`
     }
 
-    private suspend fun sleepingNestedMethod() {
-        yield() // Suspension point
-        notifyCoroutineStarted()
+    private suspend fun sleepingNestedMethod(currentDispatcher: CoroutineDispatcher, latch: CompletableDeferred<Unit>) {
+        /* Schedule a computation on the current single-threaded dispatcher.
+        Since that thread is currently running this code,
+        the start notification will happen *after* the currently running coroutine suspends. */
+        currentDispatcher.dispatch(currentDispatcher) {
+            coroutineThread = Thread.currentThread()
+            latch.complete(Unit)
+        }
         delay(Long.MAX_VALUE)
+        yield() // TCE: make sure `sleepingNestedMethod` is contained in the continuation of `delay`
     }
 
     private fun awaitCoroutine() = synchronized(monitor) {
         while (coroutineThread == null) (monitor as Object).wait()
         while (coroutineThread!!.state != Thread.State.TIMED_WAITING) {
-            // Wait until thread sleeps to have a consistent stacktrace
+            /* Wait until the thread we're awaiting goes to sleep.
+            Note: this does not establish a happens-before relationship with the thread entering `Thread.sleep`.
+            There still doesn't seem to be any guarantee that the stacktrace will be accurately updated.
+            <https://docs.oracle.com/javase/8/docs/api/java/lang/Thread.html#getStackTrace--> says that how accurate
+            a stacktrace is is implementation-dependent. */
         }
     }