add options to configure Dokka Generator Worker isolation mode.

gradle.properties

@@ -1,5 +1,5 @@
 # memory is set quite high because the tests launch a lot of processes
-org.gradle.jvmargs=-Dfile.encoding=UTF-8 -Xmx4g -XX:MaxMetaspaceSize=2g -XX:+HeapDumpOnOutOfMemoryError -XX:+AlwaysPreTouch
+org.gradle.jvmargs=-Dfile.encoding=UTF-8 -Xmx8g -XX:MaxMetaspaceSize=4g -XX:+HeapDumpOnOutOfMemoryError -XX:+AlwaysPreTouch
 
 org.gradle.caching=true
 org.gradle.configuration-cache-problems=warn

modules/dokkatoo-plugin/api/dokkatoo-plugin.api

@@ -357,13 +357,18 @@ public abstract interface annotation class dev/adamko/dokkatoo/internal/Dokkatoo
 }
 
 public abstract class dev/adamko/dokkatoo/tasks/DokkatooGenerateTask : dev/adamko/dokkatoo/tasks/DokkatooTask {
+	public final fun ClassLoaderIsolation (Lkotlin/jvm/functions/Function1;)Ldev/adamko/dokkatoo/workers/ClassLoaderIsolation;
+	public static synthetic fun ClassLoaderIsolation$default (Ldev/adamko/dokkatoo/tasks/DokkatooGenerateTask;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Ldev/adamko/dokkatoo/workers/ClassLoaderIsolation;
+	public final fun ProcessIsolation (Lkotlin/jvm/functions/Function1;)Ldev/adamko/dokkatoo/workers/ProcessIsolation;
+	public static synthetic fun ProcessIsolation$default (Ldev/adamko/dokkatoo/tasks/DokkatooGenerateTask;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Ldev/adamko/dokkatoo/workers/ProcessIsolation;
 	public abstract fun getCacheDirectory ()Lorg/gradle/api/file/DirectoryProperty;
 	public abstract fun getGenerationType ()Lorg/gradle/api/provider/Property;
 	public final fun getGenerator ()Ldev/adamko/dokkatoo/dokka/parameters/DokkaGeneratorParametersSpec;
 	public abstract fun getOutputDirectory ()Lorg/gradle/api/file/DirectoryProperty;
 	public abstract fun getPublicationEnabled ()Lorg/gradle/api/provider/Property;
 	public abstract fun getRuntimeClasspath ()Lorg/gradle/api/file/ConfigurableFileCollection;
 	public abstract fun getWorkerDebugEnabled ()Lorg/gradle/api/provider/Property;
+	public abstract fun getWorkerIsolation ()Lorg/gradle/api/provider/Property;
 	public abstract fun getWorkerJvmArgs ()Lorg/gradle/api/provider/ListProperty;
 	public abstract fun getWorkerLogFile ()Lorg/gradle/api/file/RegularFileProperty;
 	public abstract fun getWorkerMaxHeapSize ()Lorg/gradle/api/provider/Property;
@@ -400,3 +405,20 @@ public abstract class dev/adamko/dokkatoo/tasks/LogHtmlPublicationLinkTask : dev
 public final class dev/adamko/dokkatoo/tasks/LogHtmlPublicationLinkTask$Companion {
 }
 
+public abstract interface class dev/adamko/dokkatoo/workers/ClassLoaderIsolation : dev/adamko/dokkatoo/workers/WorkerIsolation {
+}
+
+public abstract interface class dev/adamko/dokkatoo/workers/ProcessIsolation : dev/adamko/dokkatoo/workers/WorkerIsolation {
+	public abstract fun getAllJvmArgs ()Lorg/gradle/api/provider/ListProperty;
+	public abstract fun getDebug ()Lorg/gradle/api/provider/Property;
+	public abstract fun getDefaultCharacterEncoding ()Lorg/gradle/api/provider/Property;
+	public abstract fun getEnableAssertions ()Lorg/gradle/api/provider/Property;
+	public abstract fun getJvmArgs ()Lorg/gradle/api/provider/ListProperty;
+	public abstract fun getMaxHeapSize ()Lorg/gradle/api/provider/Property;
+	public abstract fun getMinHeapSize ()Lorg/gradle/api/provider/Property;
+	public abstract fun getSystemProperties ()Lorg/gradle/api/provider/MapProperty;
+}
+
+public abstract interface class dev/adamko/dokkatoo/workers/WorkerIsolation {
+}
+

modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt

@@ -99,6 +99,22 @@ constructor(
       generator.dokkaSourceSets.configureDefaults(
         sourceSetScopeConvention = dokkatooExtension.sourceSetScopeDefault
       )
+
+      workerLogFile.convention(temporaryDir.resolve("dokka-worker.log"))
+//      workerIsolation.convention(ProcessIsolation {
+//        debug.convention(false)
+//        jvmArgs.convention(
+//          listOf(
+//            //"-XX:MaxMetaspaceSize=512m",
+//            "-XX:+HeapDumpOnOutOfMemoryError",
+//            "-XX:+AlwaysPreTouch", // https://github.com/gradle/gradle/issues/3093#issuecomment-387259298
+//            //"-XX:StartFlightRecording=disk=true,name={path.drop(1).map { if (it.isLetterOrDigit()) it else '-' }.joinToString("")},dumponexit=true,duration=30s",
+//            //"-XX:FlightRecorderOptions=repository=$baseDir/jfr,stackdepth=512",
+//          )
+//        )
+//      })
+      // TODO setting classloader isolation causes many test failures due to metaspace limits.
+      workerIsolation.set(ClassLoaderIsolation())
     }
 
     dokkatooExtension.dokkatooSourceSets.configureDefaults(

modules/dokkatoo-plugin/src/main/kotlin/tasks/DokkatooGenerateTask.kt

@@ -6,7 +6,10 @@ import dev.adamko.dokkatoo.dokka.parameters.DokkaModuleDescriptionKxs
 import dev.adamko.dokkatoo.dokka.parameters.builders.DokkaParametersBuilder
 import dev.adamko.dokkatoo.internal.DokkaPluginParametersContainer
 import dev.adamko.dokkatoo.internal.DokkatooInternalApi
+import dev.adamko.dokkatoo.workers.ClassLoaderIsolation
 import dev.adamko.dokkatoo.workers.DokkaGeneratorWorker
+import dev.adamko.dokkatoo.workers.ProcessIsolation
+import dev.adamko.dokkatoo.workers.WorkerIsolation
 import java.io.IOException
 import javax.inject.Inject
 import kotlinx.serialization.json.JsonElement
@@ -72,6 +75,34 @@ constructor(
   @get:Nested
   val generator: DokkaGeneratorParametersSpec = objects.newInstance(pluginsConfiguration)
 
+  @get:Nested
+  abstract val workerIsolation: Property<WorkerIsolation>
+
+  /**
+   * Create a new [ClassLoaderIsolation] options.
+   *
+   * The resulting options must be set into [workerIsolation].
+   */
+  fun ClassLoaderIsolation(configure: ClassLoaderIsolation.() -> Unit = {}): ClassLoaderIsolation =
+    objects.newInstance<ClassLoaderIsolation>().apply(configure)
+
+  /**
+   * Create a new [ProcessIsolation] options.
+   *
+   * The resulting options must be set into [workerIsolation].
+   */
+  fun ProcessIsolation(configure: ProcessIsolation.() -> Unit = {}): ProcessIsolation =
+    objects.newInstance<ProcessIsolation>().apply {
+      @Suppress("DEPRECATION")
+      run {
+        this.debug.convention(workerDebugEnabled.orElse(false))
+        this.minHeapSize.convention(workerMinHeapSize)
+        this.maxHeapSize.convention(workerMaxHeapSize)
+        this.jvmArgs.convention(workerJvmArgs)
+      }
+      configure()
+    }
+
   @get:Internal
   abstract val workerLogFile: RegularFileProperty
 
@@ -96,8 +127,26 @@ constructor(
 
     logger.info("DokkaGeneratorWorker runtimeClasspath: ${runtimeClasspath.asPath}")
 
-    val workQueue = workers.classLoaderIsolation {
-      classpath.from(runtimeClasspath)
+    val workQueue = when (val isolation = workerIsolation.get()) {
+      is ClassLoaderIsolation ->
+        workers.classLoaderIsolation {
+          classpath.from(runtimeClasspath)
+        }
+
+      is ProcessIsolation     ->
+        workers.processIsolation {
+          classpath.from(runtimeClasspath)
+          forkOptions {
+            isolation.defaultCharacterEncoding.orNull?.let(this::setDefaultCharacterEncoding)
+            isolation.debug.orNull?.let(this::setDebug)
+            isolation.enableAssertions.orNull?.let(this::setEnableAssertions)
+            isolation.maxHeapSize.orNull?.let(this::setMaxHeapSize)
+            isolation.minHeapSize.orNull?.let(this::setMinHeapSize)
+            isolation.jvmArgs.orNull?.let(this::setJvmArgs)
+            isolation.systemProperties.orNull?.let(this::systemProperties)
+            isolation.allJvmArgs.orNull?.let(this::setAllJvmArgs)
+          }
+        }
     }
 
     workQueue.submit(DokkaGeneratorWorker::class) {
@@ -161,4 +210,23 @@ constructor(
         }
       }
   }
+
+  //region Deprecated Properties
+  /** @see JavaForkOptions.getDebug */
+  @get:Internal
+  @Deprecated("moved to TODO") // TODO
+  abstract val workerDebugEnabled: Property<Boolean>
+  /** @see JavaForkOptions.getMinHeapSize */
+  @get:Internal
+  @Deprecated("moved to TODO") // TODO
+  abstract val workerMinHeapSize: Property<String>
+  /** @see JavaForkOptions.getMaxHeapSize */
+  @get:Internal
+  @Deprecated("moved to TODO") // TODO
+  abstract val workerMaxHeapSize: Property<String>
+  /** @see JavaForkOptions.jvmArgs */
+  @get:Internal
+  @Deprecated("moved to TODO") // TODO
+  abstract val workerJvmArgs: ListProperty<String>
+  //endregion
 }