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

Code before:

internal actual inline fun platformAutoreleasePool(crossinline block: () -> Unit) = block()

/**
 * Retrieves and executes a single task from the current system dispatcher ([Dispatchers.Default] or [Dispatchers.IO]).
 * Returns `0` if any task was executed, `>= 0` for number of nanoseconds to wait until invoking this method again
 * (implying that there will be a task to steal in N nanoseconds), `-1` if there is no tasks in the corresponding dispatcher at all.
 *
 * ### Invariants
 *
 *  - When invoked from [Dispatchers.Default] **thread** (even if the actual context is different dispatcher,
 *    [CoroutineDispatcher.limitedParallelism] or any in-place wrapper), it runs an arbitrary task that ended
 *    up being scheduled to [Dispatchers.Default] or its counterpart. Tasks scheduled to [Dispatchers.IO]
 *    **are not** executed[1].
 *  - When invoked from [Dispatchers.IO] thread, the same rules apply, but for blocking tasks only.
 *
 * [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

Review comment (suggestion):
```suggestion
 *     // spawn as many tasks as needed
```

Code after:

internal actual inline fun platformAutoreleasePool(crossinline block: () -> Unit) = block()

/**
 * Retrieves and executes a single task from the current system dispatcher ([Dispatchers.Default] or [Dispatchers.IO]).
 * Returns `0` if any task was executed, `>= 0` for number of nanoseconds to wait until invoking this method again
 * (implying that there will be a task to steal in N nanoseconds), `-1` if there is no tasks in the corresponding dispatcher at all.
 *
 * ### Invariants
 *
 *  - When invoked from [Dispatchers.Default] **thread** (even if the actual context is different dispatcher,
 *    [CoroutineDispatcher.limitedParallelism] or any in-place wrapper), it runs an arbitrary task that ended
 *    up being scheduled to [Dispatchers.Default] or its counterpart. Tasks scheduled to [Dispatchers.IO]
 *    **are not** executed[1].
 *  - When invoked from [Dispatchers.IO] thread, the same rules apply, but for blocking tasks only.
 *
 * [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