ScopeProvider.coroutineScope: Deliver lifecycle exceptions to CoroutineExceptionHandler instead of throwing at call-site.

[psteiger]

Change ScopeProvider.coroutineScope throwing behavior when accessing it before scope is active, or after scope is inactive.

Instead of throwing at call site, we deliver CoroutineScopeLifecycleException(message: String, cause: OutsideScopeException) to the CoroutineExceptionHandler installed at RibCoroutinesConfig.exceptionHandler.

Note

cause is always non-null, and it's either LifecycleNotStartedException or LifecycleEndedException.

Motivation

Suppose you have an interactor that starts subscribing to an Rx stream asynchronously.

class MyInteractor {
  override fun didBecomeActive() {
    runLater {
      someObservable.autoDispose(coroutineScope).subscribe()
    }
  }
}

It is possible that this Rx subscription will be triggered after interactor's already inactive. In that case, subscription will be No-Op.

This code is incorrect: Interactor is attempting to do work after it's inactive. In other words, runLater does not respect the interactor lifecycle. Still, considering this is some legacy code being migrated from Rx to Coroutines, the new code would look like the following.

class MyInteractor {
  override fun didBecomeActive() {
    runLater {
      someObservable.autoDispose(coroutineScope).subscribe()
    }
  }
}

Unlike the Rx counterpart, this code will sometimes fatally throw. If ScopeProvider.coroutineScope is called after the scope's inactive, it will throw LifecycleEndedException at call site.

Calling coroutineScope outside of lifecycle bounds is incorrect, but in order to allow for a smoother Rx migration to Coroutines, we are changing current implementation to deliver the exception to the CoroutineExceptionHandler instead of throwing at call site.

If some app decides to override the default behavior of crashing (in JVM/Android) in face of attempts to obtain coroutineScope when lifecycle is not active, one can customize RibCoroutinesConfig.exceptionHandler at app startup:

RibCoroutinesConfig.exceptionHandler = CoroutineExceptionHandler { _, throwable ->
  when (throwable) {
    is CoroutineScopeLifecycleException -> log(throwable) // only log, don't re-throw.
    else -> throw throwable
  }
}