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 @file:Suppress("unused") 6 7 package kotlinx.coroutines 8 9 import kotlinx.coroutines.internal.* 10 import kotlinx.coroutines.scheduling.* 11 import kotlin.coroutines.* 12 13 /** 14 * Name of the property that defines the maximal number of threads that are used by [Dispatchers.IO] coroutines dispatcher. 15 */ 16 public const val IO_PARALLELISM_PROPERTY_NAME: String = "kotlinx.coroutines.io.parallelism" 17 18 /** 19 * Groups various implementations of [CoroutineDispatcher]. 20 */ 21 public actual object Dispatchers { 22 /** 23 * The default [CoroutineDispatcher] that is used by all standard builders like 24 * [launch][CoroutineScope.launch], [async][CoroutineScope.async], etc. 25 * if no dispatcher nor any other [ContinuationInterceptor] is specified in their context. 26 * 27 * It is backed by a shared pool of threads on JVM. By default, the maximal level of parallelism used 28 * by this dispatcher is equal to the number of CPU cores, but is at least two. 29 * Level of parallelism X guarantees that no more than X tasks can be executed in this dispatcher in parallel. 30 */ 31 @JvmStatic 32 public actual val Default: CoroutineDispatcher = DefaultScheduler 33 34 /** 35 * A coroutine dispatcher that is confined to the Main thread operating with UI objects. 36 * This dispatcher can be used either directly or via [MainScope] factory. 37 * Usually such dispatcher is single-threaded. 38 * 39 * Access to this property may throw [IllegalStateException] if no main thread dispatchers are present in the classpath. 40 * 41 * Depending on platform and classpath it can be mapped to different dispatchers: 42 * - On JS and Native it is equivalent of [Default] dispatcher. 43 * - On JVM it is either Android main thread dispatcher, JavaFx or Swing EDT dispatcher. It is chosen by 44 * [`ServiceLoader`](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html). 45 * 46 * In order to work with `Main` dispatcher, the following artifacts should be added to project runtime dependencies: 47 * - `kotlinx-coroutines-android` for Android Main thread dispatcher 48 * - `kotlinx-coroutines-javafx` for JavaFx Application thread dispatcher 49 * - `kotlinx-coroutines-swing` for Swing EDT dispatcher 50 * 51 * In order to set a custom `Main` dispatcher for testing purposes, add the `kotlinx-coroutines-test` artifact to 52 * project test dependencies. 53 * 54 * Implementation note: [MainCoroutineDispatcher.immediate] is not supported on Native and JS platforms. 55 */ 56 @JvmStatic 57 public actual val Main: MainCoroutineDispatcher get() = MainDispatcherLoader.dispatcher 58 59 /** 60 * A coroutine dispatcher that is not confined to any specific thread. 61 * It executes initial continuation of the coroutine in the current call-frame 62 * and lets the coroutine resume in whatever thread that is used by the corresponding suspending function, without 63 * mandating any specific threading policy. Nested coroutines launched in this dispatcher form an event-loop to avoid 64 * stack overflows. 65 * 66 * ### Event loop 67 * Event loop semantics is a purely internal concept and have no guarantees on the order of execution 68 * except that all queued coroutines will be executed on the current thread in the lexical scope of the outermost 69 * unconfined coroutine. 70 * 71 * For example, the following code: 72 * ``` 73 * withContext(Dispatchers.Unconfined) { 74 * println(1) 75 * withContext(Dispatchers.Unconfined) { // Nested unconfined 76 * println(2) 77 * } 78 * println(3) 79 * } 80 * println("Done") 81 * ``` 82 * Can print both "1 2 3" and "1 3 2", this is an implementation detail that can be changed. 83 * But it is guaranteed that "Done" will be printed only when both `withContext` are completed. 84 * 85 * 86 * Note that if you need your coroutine to be confined to a particular thread or a thread-pool after resumption, 87 * but still want to execute it in the current call-frame until its first suspension, then you can use 88 * an optional [CoroutineStart] parameter in coroutine builders like 89 * [launch][CoroutineScope.launch] and [async][CoroutineScope.async] setting it to 90 * the value of [CoroutineStart.UNDISPATCHED]. 91 */ 92 @JvmStatic 93 public actual val Unconfined: CoroutineDispatcher = kotlinx.coroutines.Unconfined 94 95 /** 96 * The [CoroutineDispatcher] that is designed for offloading blocking IO tasks to a shared pool of threads. 97 * 98 * Additional threads in this pool are created and are shutdown on demand. 99 * The number of threads used by tasks in this dispatcher is limited by the value of 100 * "`kotlinx.coroutines.io.parallelism`" ([IO_PARALLELISM_PROPERTY_NAME]) system property. 101 * It defaults to the limit of 64 threads or the number of cores (whichever is larger). 102 * 103 * ### Elasticity for limited parallelism 104 * 105 * `Dispatchers.IO` has a unique property of elasticity: its views 106 * obtained with [CoroutineDispatcher.limitedParallelism] are 107 * not restricted by the `Dispatchers.IO` parallelism. Conceptually, there is 108 * a dispatcher backed by an unlimited pool of threads, and both `Dispatchers.IO` 109 * and views of `Dispatchers.IO` are actually views of that dispatcher. In practice 110 * this means that, despite not abiding by `Dispatchers.IO`'s parallelism 111 * restrictions, its views share threads and resources with it. 112 * 113 * In the following example 114 * ``` 115 * // 100 threads for MySQL connection 116 * val myMysqlDbDispatcher = Dispatchers.IO.limitedParallelism(100) 117 * // 60 threads for MongoDB connection 118 * val myMongoDbDispatcher = Dispatchers.IO.limitedParallelism(60) 119 * ``` 120 * the system may have up to `64 + 100 + 60` threads dedicated to blocking tasks during peak loads, 121 * but during its steady state there is only a small number of threads shared 122 * among `Dispatchers.IO`, `myMysqlDbDispatcher` and `myMongoDbDispatcher`. 123 * 124 * ### Implementation note 125 * 126 * This dispatcher and its views share threads with the [Default][Dispatchers.Default] dispatcher, so using 127 * `withContext(Dispatchers.IO) { ... }` when already running on the [Default][Dispatchers.Default] 128 * dispatcher typically does not lead to an actual switching to another thread. In such scenarios, 129 * the underlying implementation attempts to keep the execution on the same thread on a best-effort basis. 130 * 131 * As a result of thread sharing, more than 64 (default parallelism) threads can be created (but not used) 132 * during operations over IO dispatcher. 133 */ 134 @JvmStatic 135 public val IO: CoroutineDispatcher = DefaultIoScheduler 136 137 /** 138 * Shuts down built-in dispatchers, such as [Default] and [IO], 139 * stopping all the threads associated with them and making them reject all new tasks. 140 * Dispatcher used as a fallback for time-related operations (`delay`, `withTimeout`) 141 * and to handle rejected tasks from other dispatchers is also shut down. 142 * 143 * This is a **delicate** API. It is not supposed to be called from a general 144 * application-level code and its invocation is irreversible. 145 * The invocation of shutdown affects most of the coroutines machinery and 146 * leaves the coroutines framework in an inoperable state. 147 * The shutdown method should only be invoked when there are no pending tasks or active coroutines. 148 * Otherwise, the behavior is unspecified: the call to `shutdown` may throw an exception without completing 149 * the shutdown, or it may finish successfully, but the remaining jobs will be in a permanent dormant state, 150 * never completing nor executing. 151 * 152 * The main goal of the shutdown is to stop all background threads associated with the coroutines 153 * framework in order to make kotlinx.coroutines classes unloadable by Java Virtual Machine. 154 * It is only recommended to be used in containerized environments (OSGi, Gradle plugins system, 155 * IDEA plugins) at the end of the container lifecycle. 156 */ 157 @DelicateCoroutinesApi shutdownnull158 public fun shutdown() { 159 DefaultExecutor.shutdown() 160 // Also shuts down Dispatchers.IO 161 DefaultScheduler.shutdown() 162 } 163 } 164