1 package kotlinx.coroutines 2 3 import kotlinx.coroutines.internal.* 4 import kotlinx.coroutines.scheduling.* 5 import kotlin.coroutines.* 6 7 /** 8 * Name of the property that defines the maximal number of threads that are used by [Dispatchers.IO] coroutines dispatcher. 9 */ 10 public const val IO_PARALLELISM_PROPERTY_NAME: String = "kotlinx.coroutines.io.parallelism" 11 12 /** 13 * Groups various implementations of [CoroutineDispatcher]. 14 */ 15 public actual object Dispatchers { 16 @JvmStatic 17 public actual val Default: CoroutineDispatcher = DefaultScheduler 18 19 @JvmStatic 20 public actual val Main: MainCoroutineDispatcher get() = MainDispatcherLoader.dispatcher 21 22 @JvmStatic 23 public actual val Unconfined: CoroutineDispatcher = kotlinx.coroutines.Unconfined 24 25 /** 26 * The [CoroutineDispatcher] that is designed for offloading blocking IO tasks to a shared pool of threads. 27 * 28 * Additional threads in this pool are created and are shutdown on demand. 29 * The number of threads used by tasks in this dispatcher is limited by the value of 30 * "`kotlinx.coroutines.io.parallelism`" ([IO_PARALLELISM_PROPERTY_NAME]) system property. 31 * It defaults to the limit of 64 threads or the number of cores (whichever is larger). 32 * 33 * ### Elasticity for limited parallelism 34 * 35 * `Dispatchers.IO` has a unique property of elasticity: its views 36 * obtained with [CoroutineDispatcher.limitedParallelism] are 37 * not restricted by the `Dispatchers.IO` parallelism. Conceptually, there is 38 * a dispatcher backed by an unlimited pool of threads, and both `Dispatchers.IO` 39 * and views of `Dispatchers.IO` are actually views of that dispatcher. In practice 40 * this means that, despite not abiding by `Dispatchers.IO`'s parallelism 41 * restrictions, its views share threads and resources with it. 42 * 43 * In the following example 44 * ``` 45 * // 100 threads for MySQL connection 46 * val myMysqlDbDispatcher = Dispatchers.IO.limitedParallelism(100) 47 * // 60 threads for MongoDB connection 48 * val myMongoDbDispatcher = Dispatchers.IO.limitedParallelism(60) 49 * ``` 50 * the system may have up to `64 + 100 + 60` threads dedicated to blocking tasks during peak loads, 51 * but during its steady state there is only a small number of threads shared 52 * among `Dispatchers.IO`, `myMysqlDbDispatcher` and `myMongoDbDispatcher`. 53 * 54 * ### Implementation note 55 * 56 * This dispatcher and its views share threads with the [Default][Dispatchers.Default] dispatcher, so using 57 * `withContext(Dispatchers.IO) { ... }` when already running on the [Default][Dispatchers.Default] 58 * dispatcher typically does not lead to an actual switching to another thread. In such scenarios, 59 * the underlying implementation attempts to keep the execution on the same thread on a best-effort basis. 60 * 61 * As a result of thread sharing, more than 64 (default parallelism) threads can be created (but not used) 62 * during operations over IO dispatcher. 63 */ 64 @JvmStatic 65 public val IO: CoroutineDispatcher get() = DefaultIoScheduler 66 67 /** 68 * Shuts down built-in dispatchers, such as [Default] and [IO], 69 * stopping all the threads associated with them and making them reject all new tasks. 70 * Dispatcher used as a fallback for time-related operations (`delay`, `withTimeout`) 71 * and to handle rejected tasks from other dispatchers is also shut down. 72 * 73 * This is a **delicate** API. It is not supposed to be called from a general 74 * application-level code and its invocation is irreversible. 75 * The invocation of shutdown affects most of the coroutines machinery and 76 * leaves the coroutines framework in an inoperable state. 77 * The shutdown method should only be invoked when there are no pending tasks or active coroutines. 78 * Otherwise, the behavior is unspecified: the call to `shutdown` may throw an exception without completing 79 * the shutdown, or it may finish successfully, but the remaining jobs will be in a permanent dormant state, 80 * never completing nor executing. 81 * 82 * The main goal of the shutdown is to stop all background threads associated with the coroutines 83 * framework in order to make kotlinx.coroutines classes unloadable by Java Virtual Machine. 84 * It is only recommended to be used in containerized environments (OSGi, Gradle plugins system, 85 * IDEA plugins) at the end of the container lifecycle. 86 */ 87 @DelicateCoroutinesApi shutdownnull88 public fun shutdown() { 89 DefaultExecutor.shutdown() 90 // Also shuts down Dispatchers.IO 91 DefaultScheduler.shutdown() 92 } 93 } 94 95 /** 96 * `actual` counterpart of the corresponding `expect` declaration. 97 * Should never be used directly from JVM sources, all accesses 98 * to `Dispatchers.IO` should be resolved to the corresponding member of [Dispatchers] object. 99 * @suppress 100 */ 101 @Suppress("EXTENSION_SHADOWED_BY_MEMBER") 102 @Deprecated(message = "Should not be used directly", level = DeprecationLevel.HIDDEN) 103 public actual val Dispatchers.IO: CoroutineDispatcher get() = Dispatchers.IO 104