[K/JVM] Provide a config option to not override fork value defined in @fork

Additionally rename "forks" configuration option to "jvmForks".

Author: Abduqodiri Qurbonzoda

README.md

@@ -148,14 +148,20 @@ Available configuration options:
 * `mode`
   - "thrpt" (default) – measures number of benchmark function invocations per time
   - "avgt" – measures time per benchmark function invocation
-* `nativeFork`
-  - "perBenchmark" (default) – executes all iterations of a benchmark in the same process (one binary execution)
-  - "perIteration" – executes each iteration of a benchmark in a separate process, measures in cold Kotlin/Native runtime environment
-* `nativeGCAfterIteration` – when set to `true`, additionally collects garbage after each measuring iteration (default is `false`).
 * `include("…")` – regular expression to include benchmarks with fully qualified names matching it, as a substring
 * `exclude("…")` – regular expression to exclude benchmarks with fully qualified names matching it, as a substring
 * `param("name", "value1", "value2")` – specify a parameter for a public mutable property `name` annotated with `@Param`
 * `reportFormat` – format of report, can be `json`(default), `csv`, `scsv` or `text`
+* There are also some advanced platform-specific settings that can be configured using `advanced("…", …)` function, 
+  where the first argument is the name of the configuration parameter, and the second is its value. Valid options:
+  * (Kotlin/Native) `nativeFork`
+    - "perBenchmark" (default) – executes all iterations of a benchmark in the same process (one binary execution)
+    - "perIteration" – executes each iteration of a benchmark in a separate process, measures in cold Kotlin/Native runtime environment
+  * (Kotlin/Native) `nativeGCAfterIteration` – when set to `true`, additionally collects garbage after each measuring iteration (default is `false`).
+  * (Kotlin/JVM) `jvmForks` – number of times harness should fork (default is `1`)
+    - a non-negative integer value – the amount to use for all benchmarks included in this configuration, zero means "no fork"
+    - "definedByJmh" – let the underlying JMH determine, which uses the amount specified in [`@Fork` annotation](https://javadoc.io/static/org.openjdk.jmh/jmh-core/1.21/org/openjdk/jmh/annotations/Fork.html) defined for the benchmark function or its enclosing class,
+      or [Defaults.MEASUREMENT_FORKS (`5`)](https://javadoc.io/static/org.openjdk.jmh/jmh-core/1.21/org/openjdk/jmh/runner/Defaults.html#MEASUREMENT_FORKS) if it is not specified by `@Fork`.
 
 Time units can be NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, or their short variants such as "ms" or "ns".  
 

examples/kotlin-multiplatform/build.gradle

@@ -58,11 +58,11 @@ kotlin {
 // Configure benchmark
 benchmark {
     configurations {
-        main { // --> jvmBenchmark/jsBenchmark + benchmark
+        main { // --> jvmBenchmark, jsBenchmark, <native target>Benchmark, benchmark
             iterations = 5 // number of iterations
             iterationTime = 300
             iterationTimeUnit = "ms"
-            advanced("forks", 3)
+            advanced("jvmForks", 3)
         }
 
         params {
@@ -74,14 +74,12 @@ benchmark {
             param("unused", 6, 9)
         }
 
-        fast { // --> jvmFastBenchmark
+        fast { // --> jvmFastBenchmark, jsFastBenchmark, <native target>FastBenchmark, fastBenchmark
             include("Common")
             exclude("long")
             iterations = 5
             iterationTime = 300 // time in ms per iteration
             iterationTimeUnit = "ms" // time in ms per iteration
-            advanced("forks", 1)
-            advanced("nativeFork", "perIteration")
             advanced("nativeGCAfterIteration", "true")
         }
 
@@ -93,6 +91,15 @@ benchmark {
             iterationTimeUnit = "ms"
             reportFormat = "csv" // csv report format
         }
+
+        fork {
+            include("CommonBenchmark")
+            iterations = 5
+            iterationTime = 300
+            iterationTimeUnit = "ms"
+            advanced("jvmForks", "definedByJmh") // see README.md for possible "jvmForks" values
+            advanced("nativeFork", "perIteration") // see README.md for possible "nativeFork" values
+        }
     }
 
     // Setup configurations

runtime/commonMain/src/kotlinx/benchmark/RunnerConfiguration.kt

@@ -10,7 +10,7 @@ class RunnerConfiguration(config: String) {
     init {
         println("Config:")
         println(config)
-        
+
         println("Values:")
         println(values)
     }
@@ -33,7 +33,13 @@ class RunnerConfiguration(config: String) {
     val iterationTime = singleValueOrNull("iterationTime") { it.toLong() }
     val iterationTimeUnit = singleValueOrNull("iterationTimeUnit") { parseTimeUnit(it) }
 
-    val forks = singleValueOrNull("forks") { it.toInt() }
+    val jvmForks = singleValueOrNull("jvmForks").let { forks ->
+        val legacy = singleValueOrNull("forks")
+        if (legacy != null) {
+            println("""Deprecation warning: configuration option "forks" was renamed to "jvmForks"""")
+        }
+        forks ?: legacy
+    }
 
     val outputTimeUnit = singleValueOrNull(
         "outputTimeUnit"

runtime/jvmMain/src/kotlinx/benchmark/jvm/JvmBenchmarkRunner.kt

@@ -43,10 +43,18 @@ fun main(args: Array<String>) {
 
     val runtimeMXBean = ManagementFactory.getRuntimeMXBean()
     val jvmArgs = runtimeMXBean.inputArguments
-    when {
-        jvmArgs.any { it.contains("libasyncProfiler") } -> jmhOptions.forks(0)
-        config.forks == null -> jmhOptions.forks(1)
-        config.forks > 0 -> jmhOptions.forks(config.forks)
+    if (jvmArgs.any { it.contains("libasyncProfiler") }) {
+        jmhOptions.forks(0)
+    } else {
+        when (config.jvmForks) {
+            null -> jmhOptions.forks(1)
+            "definedByJmh" -> { /* do not override */ }
+            else -> {
+                val forks = config.jvmForks.toIntOrNull()?.takeIf { it >= 0 }
+                    ?: throw IllegalArgumentException("jvmForks: expected a non-negative integer or \"definedByJmh\" string literal")
+                jmhOptions.forks(forks)
+            }
+        }
     }
 
     val reportFormat = ResultFormatType.valueOf(config.reportFormat.uppercase())