Add checkCancelled() extension for Job / CoroutineContext / CoroutineScope

[abusalimov]

Something like:

fun CoroutineContext.checkCancelled() {
    if (this[Job]?.isCancelled == true) throw job.getCancellationException()
}

AFAIK, currently the only way to explicitly check coroutine shall still proceed (at the same time throwing a proper CancellationException with a proper stack trace) is to invoke yield(), which has a check similar to the suggested one, yet marked internal:

kotlinx.coroutines/common/kotlinx-coroutines-core-common/src/Yield.kt

Lines 29 to 32 in f62acb6

	internal fun CoroutineContext.checkCompletion() {
	val job = get(Job)
	if (job != null && !job.isActive) throw job.getCancellationException()
	}

(Job.isCancelled is equivalent to !Job.isActive when the coroutine checks that itself).

The suggestion is to expose such extension functions for Job, CoroutineContext, CoroutineScope (similarly to isActive and cancel()).

[elizarov]

What use-case do you envision for this function? Can you given an example code that uses this function, please.

[abusalimov]

  private suspend fun <R> doExecuteCommand(command: DebuggerCommand<R>,
                                           canExecuteWhileRunning: Boolean): R {
    val expirationJob =
      if (canExecuteWhileRunning) supervisorJob
      else createSessionSuspendedSupervisorJob()
    expirationJob.checkCancelled()  // don't run if the supervisor has expired already

    return withContext(coroutineDispatcher) {
      expirationJob.cancelJobOnCompletion(coroutineContext[Job]!!)
      checkCancelled()  // check again

      command.call(this.driver)
    }
  }

  companion object {
    @Throws(CancellationException::class)
    internal fun Job.checkCancelled() {
      if (!isActive) {
        @Suppress("EXPERIMENTAL_IS_NOT_ENABLED")
        @UseExperimental(InternalCoroutinesApi::class)  // need to get rid of this
        throw getCancellationException()
      }
    }
  }