suspendCoroutineOrReturn

inline suspend fun <T> suspendCoroutineOrReturn(
    crossinline block: (Continuation<T>) -> Any?
): T
(source)

Platform and version requirements: Kotlin 1.1

Obtains the current continuation instance inside suspend functions and either suspend currently running coroutine or return result immediately without suspension.

If the block returns the special COROUTINE_SUSPENDED value, it means that suspend function did suspend the execution and will not return any result immediately. In this case, the Continuation provided to the block shall be invoked at some moment in the future when the result becomes available to resume the computation.

Otherwise, the return value of the block must have a type assignable to T and represents the result of this suspend function. It means that the execution was not suspended and the Continuation provided to the block shall not be invoked. As the result type of the block is declared as Any? and cannot be correctly type-checked, its proper return type remains on the conscience of the suspend function's author.

Note that it is not recommended to call either Continuation.resume nor Continuation.resumeWithException functions synchronously in the same stackframe where suspension function is run. Use suspendCoroutine as a safer way to obtain current continuation instance.