CoroutineDispatcher
Base class to be extended by all coroutine dispatcher implementations.
If kotlinx-coroutines is used, it is recommended to avoid ContinuationInterceptor instances that are not CoroutineDispatcher implementations, as CoroutineDispatcher ensures that the debugging facilities in the newCoroutineContext function work properly.
Predefined dispatchers
The following standard implementations are provided by kotlinx.coroutines as properties on the Dispatchers object:
Dispatchers.Default is used by all standard builders if no dispatcher or any other ContinuationInterceptor is specified in their context. It uses a common pool of shared background threads. This is an appropriate choice for compute-intensive coroutines that consume CPU resources.
Dispatchers.IO(available on the JVM and Native targets) uses a shared pool of on-demand created threads and is designed for offloading of IO-intensive blocking operations (like file I/O and blocking socket I/O).Dispatchers.Main represents the UI thread if one is available.
Dispatchers.Unconfined starts coroutine execution in the current call-frame until the first suspension, at which point the coroutine builder function returns. When the coroutine is resumed, the thread from which it is resumed will run the coroutine code until the next suspension, and so on. The
Unconfineddispatcher should not normally be used in code.Calling limitedParallelism on any dispatcher creates a view of the dispatcher that limits the parallelism to the given value. This allows creating private thread pools without spawning new threads. For example,
Dispatchers.IO.limitedParallelism(4)creates a dispatcher that allows running at most 4 tasks in parallel, reusing the existing IO dispatcher threads.When thread pools completely separate from Dispatchers.Default and Dispatchers.IO are required, they can be created with
newSingleThreadContextandnewFixedThreadPoolContexton the JVM and Native targets.An arbitrary
java.util.concurrent.Executorcan be converted to a dispatcher with theasCoroutineDispatcherextension function.
Dispatch procedure
Typically, a dispatch procedure is performed as follows:
First, isDispatchNeeded is invoked to determine whether the coroutine should be dispatched or is already in the right context.
If isDispatchNeeded returns
true, the coroutine is dispatched using the dispatch method. It may take a while for the dispatcher to start the task, but the dispatch method itself may return immediately, before the task has even begun to execute.If no dispatch is needed (which is the case for Dispatchers.Main.immediate when already on the main thread and for Dispatchers.Unconfined), dispatch is typically not called, and the coroutine is resumed in the thread performing the dispatch procedure, forming an event loop to prevent stack overflows. See Dispatchers.Unconfined for a description of event loops.
This behavior may be different on the very first dispatch procedure for a given coroutine, depending on the CoroutineStart parameter of the coroutine builder.
Inheritors
Functions
Converts an instance of CoroutineDispatcher to an implementation of Executor.
Requests execution of a runnable block. The dispatcher guarantees that block will eventually execute, typically by dispatching it to a thread pool, using a dedicated thread, or just executing the block in place. The context parameter represents the context of the coroutine that is being dispatched, or EmptyCoroutineContext if a non-coroutine-specific Runnable is dispatched instead. Implementations may use context for additional context-specific information, such as priority, whether the dispatched coroutine can be invoked in place, coroutine name, and additional diagnostic elements.
Returns a continuation that wraps the provided continuation, thus intercepting all resumptions.
Calls the specified suspending block with the given CoroutineDispatcher, suspends until it completes, and returns the result.
Returns true if the execution of the coroutine should be performed with dispatch method. The default behavior for most dispatchers is to return true.
Creates a view of the current dispatcher that limits the parallelism to the given value. The resulting view uses the original dispatcher for execution but with the guarantee that no more than parallelism coroutines are executed at the same time.