1 /* 2 * Copyright 2016-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. 3 */ 4 5 package kotlinx.coroutines 6 7 import kotlin.coroutines.* 8 9 /** 10 * Groups various implementations of [CoroutineDispatcher]. 11 */ 12 public expect object Dispatchers { 13 /** 14 * The default [CoroutineDispatcher] that is used by all standard builders like 15 * [launch][CoroutineScope.launch], [async][CoroutineScope.async], etc. 16 * if neither a dispatcher nor any other [ContinuationInterceptor] is specified in their context. 17 * 18 * It is backed by a shared pool of threads on JVM and Native. By default, the maximum number of threads used 19 * by this dispatcher is equal to the number of CPU cores, but is at least two. 20 */ 21 public val Default: CoroutineDispatcher 22 23 /** 24 * A coroutine dispatcher that is confined to the Main thread operating with UI objects. 25 * Usually such dispatchers are single-threaded. 26 * 27 * Access to this property may throw an [IllegalStateException] if no main dispatchers are present in the classpath. 28 * 29 * Depending on platform and classpath, it can be mapped to different dispatchers: 30 * - On JVM it is either the Android main thread dispatcher, JavaFx, or Swing EDT dispatcher. It is chosen by the 31 * [`ServiceLoader`](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html). 32 * - On JS it is equivalent to the [Default] dispatcher with [immediate][MainCoroutineDispatcher.immediate] support. 33 * - On Native Darwin-based targets, it is a dispatcher backed by Darwin's main queue. 34 * - On other Native targets, it is a single-threaded dispatcher backed by a standalone worker. 35 * 36 * In order to work with the `Main` dispatcher, the following artifact should be added to the project runtime dependencies: 37 * - `kotlinx-coroutines-android` — for Android Main thread dispatcher 38 * - `kotlinx-coroutines-javafx` — for JavaFx Application thread dispatcher 39 * - `kotlinx-coroutines-swing` — for Swing EDT dispatcher 40 * - `kotlinx-coroutines-test` — for mocking the `Main` dispatcher in tests via `Dispatchers.setMain` 41 */ 42 public val Main: MainCoroutineDispatcher 43 44 /** 45 * A coroutine dispatcher that is not confined to any specific thread. 46 * It executes the initial continuation of a coroutine in the current call-frame 47 * and lets the coroutine resume in whatever thread that is used by the corresponding suspending function, without 48 * mandating any specific threading policy. Nested coroutines launched in this dispatcher form an event-loop to avoid 49 * stack overflows. 50 * 51 * ### Event loop 52 * Event loop semantics is a purely internal concept and has no guarantees on the order of execution 53 * except that all queued coroutines will be executed on the current thread in the lexical scope of the outermost 54 * unconfined coroutine. 55 * 56 * For example, the following code: 57 * ``` 58 * withContext(Dispatchers.Unconfined) { 59 * println(1) 60 * launch(Dispatchers.Unconfined) { // Nested unconfined 61 * println(2) 62 * } 63 * println(3) 64 * } 65 * println("Done") 66 * ``` 67 * Can print both "1 2 3" and "1 3 2". This is an implementation detail that can be changed. 68 * However, it is guaranteed that "Done" will only be printed once the code in both `withContext` and `launch` completes. 69 * 70 * If you need your coroutine to be confined to a particular thread or a thread-pool after resumption, 71 * but still want to execute it in the current call-frame until its first suspension, you can use 72 * an optional [CoroutineStart] parameter in coroutine builders like 73 * [launch][CoroutineScope.launch] and [async][CoroutineScope.async] setting it to 74 * the value of [CoroutineStart.UNDISPATCHED]. 75 */ 76 public val Unconfined: CoroutineDispatcher 77 } 78