Repository: Kotlin/kotlinx.coroutines
File: kotlinx-coroutines-core/common/src/Yield.kt (Kotlin)

Code before:
package kotlinx.coroutines

import kotlinx.coroutines.internal.*
import kotlin.coroutines.intrinsics.*

/**
 * Yields the thread (or thread pool) of the current coroutine dispatcher
 * to other coroutines on the same dispatcher to run if possible.
 *
 * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while
 * [yield] is invoked or while waiting for dispatch, it immediately resumes with [CancellationException].
 * There is a **prompt cancellation guarantee**: even if this function is ready to return the result, but was cancelled
 * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.
 *
 * **Note**: This function always [checks for cancellation][ensureActive] even when it does not suspend.
 *
 * ### Implementation details
 *
 * If the coroutine dispatcher is [Unconfined][Dispatchers.Unconfined], this
 * functions suspends only when there are other unconfined coroutines working and forming an event-loop.
 * For other dispatchers, this function calls [CoroutineDispatcher.dispatch] and
 * always suspends to be resumed later regardless of the result of [CoroutineDispatcher.isDispatchNeeded].
 * If there is no [CoroutineDispatcher] in the context, it does not suspend.
 */
public suspend fun yield(): Unit = suspendCoroutineUninterceptedOrReturn sc@ { uCont ->
    val context = uCont.context
    context.ensureActive()
    val cont = uCont.intercepted() as? DispatchedContinuation<Unit> ?: return@sc Unit
    if (cont.dispatcher.safeIsDispatchNeeded(context)) {
        // this is a regular dispatcher -- do simple dispatchYield
        cont.dispatchYield(context, Unit)
    } else {
        // This is either an "immediate" dispatcher or the Unconfined dispatcher
        // This code detects the Unconfined dispatcher even if it was wrapped into another dispatcher

Review comment (suggestion):
``` suggestion
 * A coroutine runs uninterrupted on a thread until the coroutine *suspends*,
```

Code after:
package kotlinx.coroutines

import kotlinx.coroutines.internal.*
import kotlin.coroutines.intrinsics.*

/**
 * Suspends this coroutine and immediately schedules it for further execution.
 *
 * A coroutine run uninterrupted on a thread until the coroutine *suspend*,
 * giving other coroutines a chance to use that thread for their own computations.
 * Normally, coroutines suspend whenever they wait for something to happen:
 * for example, trying to receive a value from a channel that's currently empty will suspend.
 * Sometimes, a coroutine does not need to wait for anything,
 * but we still want it to give other coroutines a chance to run.
 * Calling [yield] has this effect:
 *
 * ```
 * fun updateProgressBar(value: Int, marker: String) {
 *     print(marker)
 * }
 * val singleThreadedDispatcher = Dispatchers.Default.limitedParallelism(1)
 * withContext(singleThreadedDispatcher) {
 *     launch {
 *         repeat(5) {
 *             updateProgressBar(it, "A")
 *             yield()
 *         }
 *     }
 *     launch {
 *         repeat(5) {
 *             updateProgressBar(it, "B")
 *             yield()
 *         }
 *     }