Repository: Kotlin/kotlinx.coroutines
File: kotlinx-coroutines-core/jvm/src/EventLoop.kt (Kotlin)

Code before:
 * [1] -- this is purely technical limitation: the scheduler does not have "notify me when CPU token is available" API,
 * and we cannot leave this method without leaving thread in its original state.
 *
 * ### Rationale
 *
 * This is an internal API that is intended to replace IDEA's core FJP decomposition.
 * The following API is provided by IDEA core:
 * ```
 * runDecomposedTaskAndJoinIt { // <- non-suspending call
 *     // spawn as many task as needed
 *     // these tasks can also invoke 'runDecomposedTaskAndJoinIt'
 * }
 * ```
 * The key observation here is that 'runDecomposedTaskAndJoinIt' can be invoked from `Dispatchers.Default` itself,
 * thus blocking at least one thread. To avoid deadlocks and starvation during large hierarchical decompositions,
 * 'runDecomposedTaskAndJoinIt' should not only block, but also **help** executing the task or other tasks
 * until an arbitrary condition is satisfied.
 *
 * See #3439 for additional details.
 *
 * ### Limitations and caveats
 *
 * - Executes tasks in-place, thus potentially leaking irrelevant thread-locals from the current thread
 * - Is not 100% effective, because the caller should somehow "wait" (or do other work) during [Long] returned nanoseconds
 *   even when work arrives immediately after returning from this method.
 * - When there is no more work, it's up to the caller to decide what to do. It's important to account that
 *   work to current dispatcher may arrive **later** from external sources [1]
 *
 * [1] -- this is also a technicality that can be solved in kotlinx.coroutines itself, but unfortunately requires
 *        a tremendous effort.
 *
 * @throws IllegalStateException if the current thread is not system dispatcher thread
 */
@InternalCoroutinesApi
@DelicateCoroutinesApi
@PublishedApi
internal fun runSingleTaskFromCurrentSystemDispatcher(): Long {
    val thread = Thread.currentThread()
    if (thread !is CoroutineScheduler.Worker) throw IllegalStateException("Expected CoroutineScheduler.Worker, but got $thread")
    return thread.runSingleTask()
}

/**
 * Checks whether the given thread belongs to Dispatchers.IO.
 * Note that feature "is part of the Dispatchers.IO" is *dynamic*, meaning that the thread
 * may change this status when switching between tasks.
 *
 * This function is inteded to be used on the result of `Thread.currentThread()` for diagnostic
 * purposes, and is declared as an extension only to avoid top-level scope pollution.
 */
@InternalCoroutinesApi

Review comment (suggestion):
```suggestion
 * - When there is no more work, it's up to the caller to decide what to do. It's important to remember that
```

Code after:
 * [1] -- this is purely technical limitation: the scheduler does not have "notify me when CPU token is available" API,
 * and we cannot leave this method without leaving thread in its original state.
 *
 * ### Rationale
 *
 * This is an internal API that is intended to replace IDEA's core FJP decomposition.
 * The following API is provided by IDEA core:
 * ```
 * runDecomposedTaskAndJoinIt { // <- non-suspending call
 *     // spawn as many tasks as needed
 *     // these tasks can also invoke 'runDecomposedTaskAndJoinIt'
 * }
 * ```
 * The key observation here is that 'runDecomposedTaskAndJoinIt' can be invoked from `Dispatchers.Default` itself,
 * thus blocking at least one thread. To avoid deadlocks and starvation during large hierarchical decompositions,
 * 'runDecomposedTaskAndJoinIt' should not just block but also **help** execute the task or other tasks
 * until an arbitrary condition is satisfied.
 *
 * See #3439 for additional details.
 *
 * ### Limitations and caveats
 *
 * - Executes tasks in-place, thus potentially leaking irrelevant thread-locals from the current thread
 * - Is not 100% effective, because the caller should somehow "wait" (or do other work) for [Long] returned nanoseconds
 *   even when work arrives immediately after returning from this method.
 * - When there is no more work, it's up to the caller to decide what to do. It's important to remember that
 *   work to current dispatcher may arrive **later** from external sources [1]
 *
 * [1] -- this is also a technicality that can be solved in kotlinx.coroutines itself, but unfortunately requires
 *        a tremendous effort.
 *
 * @throws IllegalStateException if the current thread is not system dispatcher thread
 */
@InternalCoroutinesApi
@DelicateCoroutinesApi
@PublishedApi
internal fun runSingleTaskFromCurrentSystemDispatcher(): Long {
    val thread = Thread.currentThread()
    if (thread !is CoroutineScheduler.Worker) throw IllegalStateException("Expected CoroutineScheduler.Worker, but got $thread")
    return thread.runSingleTask()
}

/**
 * Checks whether the given thread belongs to Dispatchers.IO.
 * Note that feature "is part of the Dispatchers.IO" is *dynamic*, meaning that the thread
 * may change this status when switching between tasks.
 *
 * This function is inteded to be used on the result of `Thread.currentThread()` for diagnostic
 * purposes, and is declared as an extension only to avoid top-level scope pollution.
 */
@InternalCoroutinesApi