Coroutine Read Actions

The concept of read/write locks and running blocking and cancellable read actions is explained in the Threading section:

This section explains running read actions (RA) in coroutines specifically.

Coroutine Read Actions API

Running RA from coroutines is executed with *ReadAction* functions from coroutines.kt (see their KDocs for the details). Functions can be divided into two groups, which differ in reacting to an incoming write action (WA):

Write Allowing Read Action (WARA)	Write Blocking Read Action (WBRA)
`readAction`	`readActionBlocking`
`smartReadAction`	`smartReadActionBlocking`
`constrainedReadAction`	`constrainedReadActionBlocking`

WARA is canceled when a parent coroutine is canceled or a WA arrives.

WBRA is canceled only when a parent coroutine is canceled. It blocks WA until finishing its lambda.

Write Allowing Read Action vs. NonBlockingReadAction

WARA API is simpler than NonBlockingReadAction (NBRA). WARA doesn't need the following API methods:

submit(Executor backgroundThreadExecutor) because this is a responsibility of the coroutine dispatcher
executeSynchronously() because effectively they're executed in the current coroutine dispatcher already
expireWhen(BooleanSupplier expireCondition), expireWith(Disposable parentDisposable), and wrapProgress(ProgressIndicator progressIndicator) because they're canceled when the calling coroutine is canceled
finishOnUiThread() because this is handled by switching to the EDT dispatcher. Note that the UI data must be pure (for example, strings/icons/element pointers), which inherently can't be invalidated during the transfer from a background thread to EDT.
In the case of using NBRA's finishOnUiThread to start a write action, the coroutine equivalent is readAndWriteAction:
readAndWriteAction { val computedData = computeDataInReadAction() writeAction { applyData(computedData) } }
It provides the same guarantees as finishOnUIThread (no WA between computeDataInReadAction and applyData), but it is not bound to EDT.
coalesceBy(Object ... equality) because this should be handled by Flow.collectLatest() and/or Flow.distinctUntilChanged(). Usually, NBRAs are run as a reaction to user actions, and there might be multiple NBRAs running, even if their results are unused. Instead of cancelling the read action, in the coroutine world the coroutines are canceled:
eventFlow.collectLatest { event -> // the next emitted event will cancel the current coroutine // and run it again with the next event readAction { readData() } } eventFlow.distinctUntilChanged().collectLatest { event -> // the next emitted event will cancel the current coroutine // and run it again with the next event if the next event // wasn't equal to the previous one readAction { readData() } }

Read Action Cancellability

Suspending read actions use coroutines as the underlying framework.

WARA (invoked with mentioned *ReadAction functions) may make several attempts to execute its lambda. The block needs to know whether the current attempt was canceled. *ReadAction functions create a child Job for each attempt, and this job becomes canceled when a write action arrives. *ReadAction restarts the block if it was canceled by a write action, or throws CancellationException if the calling coroutine was canceled, causing the cancellation of the child Job.

To check whether the current action was canceled, clients must call ProgressManager.checkCanceled(), which was adjusted to work in coroutines. Clients mustn't throw ProcessCanceledException manually.

FAQ

Why can't I suspend inside the block?

Read actions must be short. Technically, it is possible to allow suspension during the read action, but it is complex to implement, and it still might be surprising:

        readAction {
          withContext(IO) {
            // this will be canceled and restarted on each write action
            loadTenGigabytesOfIndexes()
          }
        }
      

Also, it is impossible to solve this with a continuation interceptor like:

        object ReadAction : ContinuationInterceptor, CoroutineContext.Key<RA> {
          override val key: CoroutineContext.Key<*> get() = this
          override fun <T> interceptContinuation(
            continuation: Continuation<T>
          ): Continuation<T> {
            return Continuation(continuation.context) { result ->
              ApplicationManager.getApplication().runReadAction {
                continuation.resumeWith(result)
              }
            }
          }
        }
      

It is impossible to give it suspending semantics: the interceptor will block its thread waiting for the read lock. The interceptors shouldn't be used for that.

As of Kotlin 1.8.x, it is not possible to combine interceptors and dispatchers. Only one of them can exist in the context:

        withContext(ReadAction) {
          foo()
          withContext(Dispatchers.Default) { // replaces ReadAction in the context
            bar() // this will be called outside read action
          }
        }
      

Even if that wasn't the case, the following code will work unexpectedly:

        withContext(ReadAction) {
          val foo = foo()
          yield() // or another function which will suspend

          // At this point 'foo' crossed the boundary between two read actions =>
          // 'foo' might be invalidated if there was a write action in between.
          bar(foo)
        }
      

Last modified: 05 August 2024