Document newFixedThreadPoolContext in common code (#3994)

Fixes #3993

Author: dkhalanskyjb

kotlinx-coroutines-core/concurrent/src/MultithreadedDispatchers.common.kt

@@ -22,10 +22,10 @@ import kotlin.jvm.*
  * This is a **delicate** API. The result of this method is a closeable resource with the
  * associated native resources (threads or native workers). It should not be allocated in place,
  * should be closed at the end of its lifecycle, and has non-trivial memory and CPU footprint.
- * If you do not need a separate thread-pool, but only have to limit effective parallelism of the dispatcher,
+ * If you do not need a separate thread pool, but only have to limit effective parallelism of the dispatcher,
  * it is recommended to use [CoroutineDispatcher.limitedParallelism] instead.
  *
- * If you need a completely separate thread-pool with scheduling policy that is based on the standard
+ * 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.
@@ -37,5 +37,30 @@ import kotlin.jvm.*
 public fun newSingleThreadContext(name: String): CloseableCoroutineDispatcher =
     newFixedThreadPoolContext(1, name)
 
+/**
+ * Creates a coroutine execution context with the fixed-size thread-pool and built-in [yield] support.
+ * **NOTE: The resulting [CoroutineDispatcher] owns native resources (its threads).
+ * Resources are reclaimed by [CloseableCoroutineDispatcher.close].**
+ *
+ * If the resulting dispatcher is [closed][CloseableCoroutineDispatcher.close] and
+ * attempt to submit a continuation task is made,
+ * * On the JVM, the [Job] of the affected task is [cancelled][Job.cancel] and the task is submitted to the
+ *   [Dispatchers.IO], so that the affected coroutine can clean up its resources and promptly complete.
+ * * On Native, the attempt to submit a task throws an exception.
+ *
+ * This is a **delicate** API. The result of this method is a closeable resource with the
+ * associated native resources (threads or native workers). It should not be allocated in place,
+ * should be closed at the end of its lifecycle, and has non-trivial memory and CPU footprint.
+ * If you do not need a separate thread pool, but only have to limit effective parallelism of the dispatcher,
+ * it is recommended to use [CoroutineDispatcher.limitedParallelism] instead.
+ *
+ * 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.
+ */
 @ExperimentalCoroutinesApi
 public expect fun newFixedThreadPoolContext(nThreads: Int, name: String): CloseableCoroutineDispatcher

kotlinx-coroutines-core/jvm/src/ThreadPoolDispatcher.kt

@@ -9,30 +9,6 @@ package kotlinx.coroutines
 import java.util.concurrent.*
 import java.util.concurrent.atomic.AtomicInteger
 
-/**
- * Creates a coroutine execution context with the fixed-size thread-pool and built-in [yield] support.
- * **NOTE: The resulting [ExecutorCoroutineDispatcher] owns native resources (its threads).
- * Resources are reclaimed by [ExecutorCoroutineDispatcher.close].**
- *
- * If the resulting dispatcher is [closed][ExecutorCoroutineDispatcher.close] and
- * attempt to submit a continuation task is made,
- * then the [Job] of the affected task is [cancelled][Job.cancel] and the task is submitted to the
- * [Dispatchers.IO], so that the affected coroutine can cleanup its resources and promptly complete.
- *
- * This is a **delicate** API. The result of this method is a closeable resource with the
- * associated native resources (threads). It should not be allocated in place,
- * should be closed at the end of its lifecycle, and has non-trivial memory and CPU footprint.
- * If you do not need a separate thread-pool, but only have to limit effective parallelism of the dispatcher,
- * it is recommended to use [CoroutineDispatcher.limitedParallelism] instead.
- *
- * 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.
- */
 @DelicateCoroutinesApi
 public actual fun newFixedThreadPoolContext(nThreads: Int, name: String): ExecutorCoroutineDispatcher {
     require(nThreads >= 1) { "Expected at least one thread, but $nThreads specified" }