From b3feffc8fc49ea8b76e08072fdd7039f01a69777 Mon Sep 17 00:00:00 2001 From: Roman Elizarov Date: Sat, 6 Oct 2018 15:36:13 +0200 Subject: [PATCH] Mark newSingle/FixedThreadPoolContext as obsolete, document the reason * The will be replaced by another mechanism in the future. See #261 for details. * The proposed replacement is to use the standard java API: Executors.newSingleThreadExecutor/newFixedThreadPool and convert to dispatcher via asCoroutineDispatcher() extension. --- .../src/ThreadPoolDispatcher.kt | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/core/kotlinx-coroutines-core/src/ThreadPoolDispatcher.kt b/core/kotlinx-coroutines-core/src/ThreadPoolDispatcher.kt index 6a563967e7..37f17b9474 100644 --- a/core/kotlinx-coroutines-core/src/ThreadPoolDispatcher.kt +++ b/core/kotlinx-coroutines-core/src/ThreadPoolDispatcher.kt @@ -14,8 +14,19 @@ import kotlin.coroutines.experimental.* * **NOTE: The resulting [ExecutorCoroutineDispatcher] owns native resources (its thread). * Resources are reclaimed by [ExecutorCoroutineDispatcher.close].** * + * **NOTE: This API will be replaced in the future**. A different API to create thread-limited thread pools + * that is based on a shared thread-pool and does not require the resulting dispatcher to be explicitly closed + * will be provided, thus avoiding potential thread leaks and also significantly improving performance, due + * to coroutine-oriented scheduling policy and thread-switch minimization. + * See [issue #261](https://github.com/Kotlin/kotlinx.coroutines/issues/261) for details. + * If you need a completely separate thread-pool with scheduling policy that is based on the standard + * JDK executors, use the following expression: + * `Executors.newSingleThreadExecutor().asCoroutineDispatcher()`. + * See [Executor.asCoroutineDispatcher] for details. + * * @param name the base name of the created thread. */ +@ObsoleteCoroutinesApi fun newSingleThreadContext(name: String): ExecutorCoroutineDispatcher = newFixedThreadPoolContext(1, name) @@ -40,9 +51,20 @@ fun newSingleThreadContext(name: String, parent: Job? = null): CoroutineContext * **NOTE: The resulting [ExecutorCoroutineDispatcher] owns native resources (its threads). * Resources are reclaimed by [ExecutorCoroutineDispatcher.close].** * + * **NOTE: This API will be replaced in the future**. A different API to create thread-limited thread pools + * that is based on a shared thread-pool and does not require the resulting dispatcher to be explicitly closed + * will be provided, thus avoiding potential thread leaks and also significantly improving performance, due + * to coroutine-oriented scheduling policy and thread-switch minimization. + * See [issue #261](https://github.com/Kotlin/kotlinx.coroutines/issues/261) for details. + * If you need a completely separate thread-pool with scheduling policy that is based on the standard + * JDK executors, use the following expression: + * `Executors.newFixedThreadPool().asCoroutineDispatcher()`. + * See [Executor.asCoroutineDispatcher] for details. + * * @param nThreads the number of threads. * @param name the base name of the created threads. */ +@ObsoleteCoroutinesApi fun newFixedThreadPoolContext(nThreads: Int, name: String): ExecutorCoroutineDispatcher { require(nThreads >= 1) { "Expected at least one thread, but $nThreads specified" } return ThreadPoolDispatcher(nThreads, name)