Shutdown coroutines dispatchers after each module pass (#2325)

* Update kotlinx.coroutines to 1.6.0

* Shutdown common coroutines dispatchers after each module pass

* Don't finalize coroutines in unit tests

Co-authored-by: Mikhail Zarechenskiy <mikhail.zarechenskiy@jetbrains.com>

3 files changed, 24 insertions, 23 deletions

diff --git a/core/src/main/kotlin/DokkaGenerator.kt b/core/src/main/kotlin/DokkaGenerator.kt
index 9241d728..a14775cb 100644
--- a/core/src/main/kotlin/DokkaGenerator.kt
+++ b/core/src/main/kotlin/DokkaGenerator.kt
@@ -2,15 +2,12 @@
 
 package org.jetbrains.dokka
 
+import kotlinx.coroutines.DelicateCoroutinesApi
 import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.InternalCoroutinesApi
-import kotlinx.coroutines.scheduling.ExperimentalCoroutineDispatcher
 import org.jetbrains.dokka.generation.GracefulGenerationExit
 import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.plugability.DokkaPlugin
 import org.jetbrains.dokka.utilities.DokkaLogger
-import kotlin.reflect.full.memberProperties
-import kotlin.reflect.jvm.isAccessible
 
 /**
  * DokkaGenerator is the main entry point for generating documentation
@@ -45,28 +42,12 @@ class DokkaGenerator(
         additionalPlugins: List<DokkaPlugin> = emptyList()
     ) = DokkaContext.create(configuration, logger, additionalPlugins)
 
+    @OptIn(DelicateCoroutinesApi::class)
     private fun finalizeCoroutines() {
-        runCatching {
-            Dispatchers.Default.closeExecutor()
-
-            Dispatchers.IO.let { dispatcher ->
-                dispatcher::class.memberProperties.find {
-                    it.name == "dispatcher"
-                }?.also {
-                    it.isAccessible = true
-                }?.call(dispatcher)
-            }?.closeExecutor()
+        if (configuration.finalizeCoroutines) {
+            Dispatchers.shutdown()
         }
     }
-
-    @OptIn(InternalCoroutinesApi::class)
-    private fun Any.closeExecutor() = (this as ExperimentalCoroutineDispatcher).also {
-        it.executor::class.members
-            .find { it.name == "close" }
-            ?.also {
-                it.isAccessible = true
-            }?.call(it.executor)
-    }
 }
 
 class Timer internal constructor(startTime: Long, private val logger: DokkaLogger?) {
diff --git a/core/src/main/kotlin/configuration.kt b/core/src/main/kotlin/configuration.kt
index 038a5bb7..ebd6ed61 100644
--- a/core/src/main/kotlin/configuration.kt
+++ b/core/src/main/kotlin/configuration.kt
@@ -134,6 +134,25 @@ interface DokkaConfiguration : Serializable {
     val includes: Set<File>
     val suppressInheritedMembers: Boolean
 
+    /**
+     * Whether coroutines dispatchers should be shutdown after
+     * generating documentation via [DokkaGenerator.generate].
+     *
+     * It effectively stops all background threads associated with
+     * coroutines in order to make classes unloadable by the JVM,
+     * and rejects all new tasks with [RejectedExecutionException]
+     *
+     * This is primarily useful for multi-module builds where coroutines
+     * can be shut down after each module's partial task to avoid
+     * possible memory leaks.
+     *
+     * However, this can lead to problems in specific lifecycles where
+     * coroutines are shared and will be reused after documentation generation,
+     * and closing it down will leave the build in an inoperable state.
+     * One such example is unit tests, for which finalization should be disabled.
+     */
+    val finalizeCoroutines: Boolean
+
     enum class SerializationFormat : Serializable {
         JSON, XML
     }
diff --git a/core/src/main/kotlin/defaultConfiguration.kt b/core/src/main/kotlin/defaultConfiguration.kt
index 4d23ce68..d4f92f33 100644
--- a/core/src/main/kotlin/defaultConfiguration.kt
+++ b/core/src/main/kotlin/defaultConfiguration.kt
@@ -19,6 +19,7 @@ data class DokkaConfigurationImpl(
     override val suppressObviousFunctions: Boolean = DokkaDefaults.suppressObviousFunctions,
     override val includes: Set<File> = emptySet(),
     override val suppressInheritedMembers: Boolean = DokkaDefaults.suppressInheritedMembers,
+    override val finalizeCoroutines: Boolean = true,
 ) : DokkaConfiguration
 
 data class PluginConfigurationImpl(