1 @file:JvmMultifileClass
2 @file:JvmName("ThreadPoolDispatcherKt")
3 package kotlinx.coroutines
4
5 import kotlin.jvm.*
6
7 /**
8 * Creates a coroutine execution context using a single thread with built-in [yield] support.
9 * **NOTE: The resulting [CloseableCoroutineDispatcher] owns native resources (its thread).
10 * Resources are reclaimed by [CloseableCoroutineDispatcher.close].**
11 *
12 * If the resulting dispatcher is [closed][CloseableCoroutineDispatcher.close] and
13 * attempt to submit a task is made, then:
14 * - On the JVM, the [Job] of the affected task is [cancelled][Job.cancel] and the task is submitted to the
15 * [Dispatchers.IO], so that the affected coroutine can clean up its resources and promptly complete.
16 * - On Native, the attempt to submit a task throws an exception.
17 *
18 * This is a **delicate** API. The result of this method is a closeable resource with the
19 * associated native resources (threads or native workers). It should not be allocated in place,
20 * should be closed at the end of its lifecycle, and has non-trivial memory and CPU footprint.
21 * If you do not need a separate thread pool, but only have to limit effective parallelism of the dispatcher,
22 * it is recommended to use [`Dispatchers.IO.limitedParallelism(1)`][CoroutineDispatcher.limitedParallelism]
23 * or [`Dispatchers.Default.limitedParallelism(1)`][CoroutineDispatcher.limitedParallelism] instead.
24 *
25 * If you need a completely separate thread pool with scheduling policy that is based on the standard
26 * JDK executors, use the following expression:
27 * `Executors.newSingleThreadExecutor().asCoroutineDispatcher()`.
28 * See `Executor.asCoroutineDispatcher` for details.
29 *
30 * @param name the base name of the created thread.
31 */
32 @ExperimentalCoroutinesApi
33 @DelicateCoroutinesApi
newSingleThreadContextnull34 public fun newSingleThreadContext(name: String): CloseableCoroutineDispatcher =
35 newFixedThreadPoolContext(1, name)
36
37 /**
38 * Creates a coroutine execution context with the fixed-size thread-pool and built-in [yield] support.
39 * **NOTE: The resulting [CoroutineDispatcher] owns native resources (its threads).
40 * Resources are reclaimed by [CloseableCoroutineDispatcher.close].**
41 *
42 * If the resulting dispatcher is [closed][CloseableCoroutineDispatcher.close] and
43 * attempt to submit a continuation task is made,
44 * - On the JVM, the [Job] of the affected task is [cancelled][Job.cancel] and the task is submitted to the
45 * [Dispatchers.IO], so that the affected coroutine can clean up its resources and promptly complete.
46 * - On Native, the attempt to submit a task throws an exception.
47 *
48 * This is a **delicate** API. The result of this method is a closeable resource with the
49 * associated native resources (threads or native workers). It should not be allocated in place,
50 * should be closed at the end of its lifecycle, and has non-trivial memory and CPU footprint.
51 * If you do not need a separate thread pool, but only have to limit effective parallelism of the dispatcher,
52 * it is recommended to use [`Dispatchers.IO.limitedParallelism(nThreads)`][CoroutineDispatcher.limitedParallelism]
53 * or [`Dispatchers.Default.limitedParallelism(nThreads)`][CoroutineDispatcher.limitedParallelism] instead.
54 *
55 * If you need a completely separate thread pool with scheduling policy that is based on the standard
56 * JDK executors, use the following expression:
57 * `Executors.newFixedThreadPool().asCoroutineDispatcher()`.
58 * See `Executor.asCoroutineDispatcher` for details.
59 *
60 * @param nThreads the number of threads.
61 * @param name the base name of the created threads.
62 */
63 @ExperimentalCoroutinesApi
64 @DelicateCoroutinesApi
65 public expect fun newFixedThreadPoolContext(nThreads: Int, name: String): CloseableCoroutineDispatcher
66