1 /* 2 * Copyright 2016-2018 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. 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 JS and Native it is equivalent to the [Default] dispatcher. 31 * - On JVM it either the Android main thread dispatcher, JavaFx or Swing EDT dispatcher. It is chosen by the 32 * [`ServiceLoader`](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html). 33 * 34 * In order to work with the `Main` dispatcher, the following artifact should be added to the project runtime dependencies: 35 * - `kotlinx-coroutines-android` — for Android Main thread dispatcher 36 * - `kotlinx-coroutines-javafx` — for JavaFx Application thread dispatcher 37 * - `kotlinx-coroutines-swing` — for Swing EDT dispatcher 38 * 39 * Implementation note: [MainCoroutineDispatcher.immediate] is not supported on the Native and JS platforms. 40 */ 41 public val Main: MainCoroutineDispatcher 42 43 /** 44 * A coroutine dispatcher that is not confined to any specific thread. 45 * It executes the initial continuation of a coroutine in the current call-frame 46 * and lets the coroutine resume in whatever thread that is used by the corresponding suspending function, without 47 * mandating any specific threading policy. Nested coroutines launched in this dispatcher form an event-loop to avoid 48 * stack overflows. 49 * 50 * ### Event loop 51 * Event loop semantics is a purely internal concept and have no guarantees on the order of execution 52 * except that all queued coroutines will be executed on the current thread in the lexical scope of the outermost 53 * unconfined coroutine. 54 * 55 * For example, the following code: 56 * ``` 57 * withContext(Dispatcher.Unconfined) { 58 * println(1) 59 * withContext(Dispatcher.Unconfined) { // Nested unconfined 60 * println(2) 61 * } 62 * println(3) 63 * } 64 * println("Done") 65 * ``` 66 * Can print both "1 2 3" and "1 3 2", this is an implementation detail that can be changed. 67 * But it is guaranteed that "Done" will be printed only when both `withContext` calls are completed. 68 * 69 * Note that if you need your coroutine to be confined to a particular thread or a thread-pool after resumption, 70 * but still want to execute it in the current call-frame until its first suspension, then you can use 71 * an optional [CoroutineStart] parameter in coroutine builders like 72 * [launch][CoroutineScope.launch] and [async][CoroutineScope.async] setting it to 73 * the value of [CoroutineStart.UNDISPATCHED]. 74 */ 75 public val Unconfined: CoroutineDispatcher 76 } 77