perf(rendering): make rendering parallel

Author: iamgio

.run/CLI_ Docs.run.xml

@@ -0,0 +1,12 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="CLI: Docs" type="JetRunConfigurationType">
+    <option name="MAIN_CLASS_NAME" value="com.quarkdown.cli.QuarkdownCliKt" />
+    <module name="quarkdown.quarkdown-cli.main" />
+    <option name="PROGRAM_PARAMETERS" value="c main.qd --strict --allow all --clean --libs ../quarkdown-libs/src/main/resources --out-name wiki --allow all" />
+    <shortenClasspath name="NONE" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/docs" />
+    <method v="2">
+      <option name="Make" enabled="true" />
+    </method>
+  </configuration>
+</component>

quarkdown-core/build.gradle.kts

@@ -23,6 +23,7 @@ dependencies {
     cslStyles("org.citationstyles:styles:26.2")
     implementation("org.citationstyles:locales:26.2")
     implementation("org.jetbrains.kotlinx:kotlinx-collections-immutable:0.4.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
 }
 
 // Extracts only the CSL style files listed in csl-styles.txt from the full styles collection, to reduce the bundle size.

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/Node.kt

@@ -1,5 +1,6 @@
 package com.quarkdown.core.ast
 
+import com.quarkdown.core.util.mapParallel
 import com.quarkdown.core.visitor.node.NodeVisitor
 
 /**
@@ -37,3 +38,19 @@ interface SingleChildNestableNode<T : Node> : NestableNode {
     override val children: List<Node>
         get() = listOf(child)
 }
+
+/**
+ * Accepts a visitor for each node sequentially.
+ * @param visitor the visitor to accept
+ * @return the list of results from each visit, preserving order
+ */
+fun <T> List<Node>.acceptAll(visitor: NodeVisitor<T>): List<T> = map { it.accept(visitor) }
+
+/**
+ * Accepts a visitor for each node, executing visits in parallel when beneficial.
+ * Falls back to sequential execution for small lists.
+ * @param visitor the visitor to accept
+ * @return the list of results from each visit, preserving order
+ * @see mapParallel
+ */
+fun <T> List<Node>.parallelAcceptAll(visitor: NodeVisitor<T>): List<T> = mapParallel { it.accept(visitor) }

quarkdown-core/src/main/kotlin/com/quarkdown/core/property/AssociatedProperties.kt

@@ -1,5 +1,8 @@
 package com.quarkdown.core.property
 
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.ConcurrentMap
+
 /**
  * Associations between a key of type [T] and a [PropertyContainer].
  *
@@ -30,7 +33,7 @@ interface AssociatedProperties<T, V> {
  * Mutable implementation of [AssociatedProperties].
  */
 class MutableAssociatedProperties<T, V> : AssociatedProperties<T, V> {
-    private val properties: MutableMap<T, MutablePropertyContainer<V>> = mutableMapOf()
+    private val properties: ConcurrentMap<T, MutablePropertyContainer<V>> = ConcurrentHashMap()
 
-    override fun of(key: T): MutablePropertyContainer<V> = properties.getOrPut(key) { MutablePropertyContainer() }
+    override fun of(key: T): MutablePropertyContainer<V> = properties.computeIfAbsent(key) { MutablePropertyContainer() }
 }

quarkdown-core/src/main/kotlin/com/quarkdown/core/rendering/tag/TagBuilder.kt

@@ -1,6 +1,7 @@
 package com.quarkdown.core.rendering.tag
 
 import com.quarkdown.core.ast.Node
+import com.quarkdown.core.ast.parallelAcceptAll
 
 /**
  * A builder of a generic output code wrapped within tags (of any kind) which can be unlimitedly nested.
@@ -68,7 +69,7 @@ abstract class TagBuilder(
      * Usage: `+someNode.children`
      */
     operator fun List<Node>.unaryPlus() {
-        forEach { +it }
+        parallelAcceptAll(renderer).forEach { +it }
     }
 }
 

quarkdown-core/src/main/kotlin/com/quarkdown/core/util/ConcurrencyUtils.kt

@@ -0,0 +1,67 @@
+package com.quarkdown.core.util
+
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.async
+import kotlinx.coroutines.awaitAll
+import kotlinx.coroutines.coroutineScope
+import kotlinx.coroutines.runBlocking
+
+/**
+ * Minimum number of items required for parallel execution to be worthwhile.
+ * Below this threshold, the overhead of coroutine scheduling exceeds the benefit.
+ */
+private const val MIN_ITEMS_FOR_PARALLELISM = 4
+
+/**
+ * Tracks whether the current thread is already inside a [mapParallel] invocation,
+ * preventing nested [runBlocking] calls that would risk thread pool exhaustion.
+ */
+private val insideParallelBlock = ThreadLocal.withInitial { false }
+
+/**
+ * Maps each element of this list using [transform], executing transformations in parallel
+ * via coroutines when the list is large enough to benefit from concurrency.
+ * Falls back to sequential mapping for small lists where coroutine overhead exceeds benefit.
+ *
+ * Handles nested invocations safely: if already executing inside a parallel block,
+ * the inner call uses [coroutineScope] instead of [runBlocking] to avoid thread pool exhaustion.
+ *
+ * Results are returned in the same order as the input list.
+ * @param transform the transformation to apply to each element
+ * @return the list of transformed results, preserving input order
+ */
+fun <T, R> List<T>.mapParallel(transform: (T) -> R): List<R> {
+    if (size < MIN_ITEMS_FOR_PARALLELISM) {
+        return map(transform)
+    }
+
+    // If already inside a parallel block, delegate to a suspending coroutineScope
+    // to participate in the existing dispatcher without blocking a thread.
+    if (insideParallelBlock.get()) {
+        return runBlocking {
+            mapParallelAsync(transform)
+        }
+    }
+
+    return runBlocking(Dispatchers.Default) {
+        mapParallelAsync(transform)
+    }
+}
+
+/**
+ * Suspending implementation of parallel mapping.
+ * Launches an [async] coroutine per element and awaits all results in order.
+ */
+private suspend fun <T, R> List<T>.mapParallelAsync(transform: (T) -> R): List<R> =
+    coroutineScope {
+        map { element ->
+            async {
+                insideParallelBlock.set(true)
+                try {
+                    transform(element)
+                } finally {
+                    insideParallelBlock.set(false)
+                }
+            }
+        }.awaitAll()
+    }

quarkdown-plaintext/src/main/kotlin/com/quarkdown/rendering/plaintext/node/PlainTextNodeRenderer.kt

@@ -39,6 +39,7 @@ import com.quarkdown.core.ast.base.inline.StrongEmphasis
 import com.quarkdown.core.ast.base.inline.SubdocumentLink
 import com.quarkdown.core.ast.base.inline.Text
 import com.quarkdown.core.ast.dsl.buildBlock
+import com.quarkdown.core.ast.parallelAcceptAll
 import com.quarkdown.core.ast.quarkdown.CaptionableNode
 import com.quarkdown.core.ast.quarkdown.FunctionCallNode
 import com.quarkdown.core.ast.quarkdown.bibliography.BibliographyCitation
@@ -91,7 +92,7 @@ class PlainTextNodeRenderer(
 ) : NodeRenderer {
     private fun NestableNode.visitChildren() = children.visitAll()
 
-    private fun InlineContent.visitAll() = joinToString(separator = "") { it.accept(this@PlainTextNodeRenderer) }
+    private fun InlineContent.visitAll() = parallelAcceptAll(this@PlainTextNodeRenderer).joinToString(separator = "")
 
     private val String.blockNode: String
         get() =