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