Guidance on custom implementations of coroutine dispatchers, and usage of `Delay`

[martaciesielska]

I've been working on some code that uses a custom implementation of
CoroutineDispatcher for testing. Our test dispatcher uses fake time, and runs
everything on a single thread to ensure that tests are deterministic. It's not
appropriate for end-to-end testing but it works well with a lot of unit tests
(simplicity, speed, determinism). Due to the
inner workings of Kotlin coroutines,
we made our custom dispatcher implement the Delay interface to be able to
control scheduling, even though Delay is marked as
an internal API.

Additionally to the test dispatcher, we want to maintain a coroutine dispatcher
decorator that facilitates dispatch/suspension observability. This decorator
would look something like this:

internal class CoroutineDispatcherDecorator(
  private val delegate: CoroutineDispatcher,
  private val observer: Observer, // our interface for observing some events in the system
) : CoroutineDispatcher() {

  override fun dispatch(context: CoroutineContext, block: Runnable) {
    observer.onDispatch(context)
    delegate.dispatch(context) {
      try {
        block.run()
      } finally {
        observer.onSuspend(context)
      }
    }
  }
}

With this decorator, we run into another problem with Delay: if delegate
actually implements it, we hide it by using the decorator.

Given the above, I wanted to ask some questions:

1. Are there any plans to make Delay public or provide some other public API
   in its place? I've seen
   one issue from 2020
   where it was actually recommended to someone to implement Delay, is this
   advice up-to-date? I understand that if we use Delay, we run the risk of our
   code getting broken with some future release of Kotlin coroutines.

2. If not, are custom implementations of dispatchers discouraged? Neither
   CoroutineDispatcher nor ContinuationInterceptor are marked as internal so at
   first glance it seems like this is OK but not implementing Delay could lead to
   unexpected behaviour. Is there any guidance on this (I haven't found it in the
   documentation but maybe I've missed it)?

[dkhalanskyjb]

Why do you want to implement your custom CoroutineDispatcher for testing with fake time, when we already provide such a mechanism https://github.com/Kotlin/kotlinx.coroutines/tree/master/kotlinx-coroutines-test?

I think you raise an interesting point regarding cases when you want to decorate a dispatcher while keeping the Delay implementation. This is not my first time seeing people wrapping our dispatchers with something. Maybe we should provide some proper way to do just that while keeping the Delay implementation, something like class CoroutineDispatcherWrapper(wrapped: CoroutineDispatcher): CoroutineDispatcher(), Delay. Would this cover your use case?

[martaciesielska]

Why do you want to implement your custom CoroutineDispatcher for testing with fake time, when we already provide such a mechanism https://github.com/Kotlin/kotlinx.coroutines/tree/master/kotlinx-coroutines-test?

1. It's marked as experimental which is a bit of a deterrent (maybe not as strong as internal but still).

2. It doesn't give us the same amount of flexibility - apart from manipulating time, in some cases we also enforce certain rules as to which work items get priority for execution, to simulate race conditions that we know might occur in a live system.

3. On the flip side of point 2), having our own dispatcher also gives us an opportunity to remove complexity where we don't need it if we're not using particular coroutines' features, which can make for very easy debugging.

I think you raise an interesting point regarding cases when you want to decorate a dispatcher while keeping the Delay implementation. This is not my first time seeing people wrapping our dispatchers with something. Maybe we should provide some proper way to do just that while keeping the Delay implementation, something like class CoroutineDispatcherWrapper(wrapped: CoroutineDispatcher): CoroutineDispatcher(), Delay. Would this cover your use case?

That would definitely help with the decorator we want to put in our production code.

I'd still be keen to have a mechanism to implement my own dispatcher with scheduling support for testing, for the reasons listed above. Albeit not ideal, I'd be fine with using the wrapper if it allowed intercepting scheduling.

[martaciesielska]

Hi! Any updates on this? I’d really be keen to stop relying on the internal API for the decorator at least.

[qwwdfsad]

Not many updates, unfortunately.
For Delay to be useful, it requires a non-trivial rework and rethinking from the ground up, and it's slightly out of our scope right now.

Depending on internal API is okay-ish as long as it's done on the application level, not on the library one (e.g. Delay is not used by 3rd-party libraries that are shipped to be used by other clients that also depend on coroutines), Delay won't be broken on a single release basis and there will be a proper deprecation cycle

[bejibx]

Is it ok to wrap CoroutineDispatcher like this:

abstract class CoroutineDispatcherWrapper(
    private val dispatcher: CoroutineDispatcher,
) : CoroutineContext.Element {

    override val key: CoroutineContext.Key<*> = dispatcher.key

    override fun <R> fold(initial: R, operation: (R, CoroutineContext.Element) -> R): R {
        return operation(initial, dispatcher)
    }

    override fun <E : CoroutineContext.Element> get(key: CoroutineContext.Key<E>): E? {
        @Suppress("UNCHECKED_CAST")
        return if (this.key == key) dispatcher as E else null
    }

    override fun minusKey(key: CoroutineContext.Key<*>): CoroutineContext {
        return if (this.key == key) EmptyCoroutineContext else dispatcher
    }
}

looks like in this case wrapper is disappearing when added to CoroutineScope and this is exactly what I need. If you curios why am I doing this, it's for DI. In my team we are always using concrete classes when requesting dependencies. For example with RxJava:

class SomeRepository(
    private val workerScheduler: WorkerScheduler, 
    private val timerScheduler: TimerScheduler,
) {
    // ...
}

where WorkerScheduler and TimerScheduler are just our named wrappers around io.reactivex.Scheduler. I'm trying to do same thing with CoroutineDispatcher's and now I'm curios is it ok to wrap them like this or it can cause some unexpected problems?

[kenyee]

Maybe we should provide some proper way to do just that while keeping the Delay implementation, something like class CoroutineDispatcherWrapper(wrapped: CoroutineDispatcher): CoroutineDispatcher(), Delay.

FWIW, I think this would be helpful. Our use case is somewhat similar...we want to add Espresso idling resource wrappers for the coroutine dispatchers.

[zach-klippenstein]

The CoroutineDispatcherWrapper proposal above should cover a use case I have in square/workflow-kotlin#1364, although I do not think it would cover the Compose code that needs this but for a non-dispatcher ContinuationInterceptor.

[samubura]

@zach-klippenstein, thanks for sharing your solution.
I encountered similar issues since for my implementation I want to be able to enqueue continuations and run them only when I want to so I ended up implementing a custom interceptor/dispatcher.

With the wrapper that keeps the reference to the original dispatcher delay implementation I seem to be able to inherit the virtual-time delay from the runTest with no problems so far. Without it, my understanding is that the coroutine framework falls back to the default delay which runs on machine time.

I wonder if some other guarantees are lost with this approach, otherwise it seems like a very reasonable solution.