Introduce benchmarks module with basic formatting benchmark

Author: qwwdfsad

.gitignore

@@ -4,4 +4,5 @@
 *.iml
 target
 build
-/local.properties
+/local.properties
+benchmarks.jar

benchmarks/README.md

@@ -0,0 +1,28 @@
+### Benchmarks utility module
+
+Module that provides benchmarking infrastructure for kotlinx-datetime.
+Please note that these benchmarks are typically written with the specific target, hypothesis and effect in mind.
+
+They provide numbers, not insights, and shouldn't be used as the generic comparison and statements like
+"X implementaiton or format is faster/slower than Y"
+
+
+#### Usage
+
+```
+// Build `benchmarks.jar` into the project's root
+./gradlew :benchmarks:jmhJar
+
+// Run all benchmarks
+java -jar benchmarks.jar
+
+// Run dedicated benchmark(s)
+java -jar benchmarks.jar Formatting
+java -jar benchmarks.jar FormattingBenchmark.formatIso
+
+// Run with the specified number of warmup iterations, measurement iterations, timeunit and mode
+java -jar benchmarks.jar -wi 5 -i 5 -tu us -bm thrpt Formatting
+
+// Extensive help
+java -jar benchmarks.jar -help
+```

benchmarks/build.gradle.kts

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2019-2023 JetBrains s.r.o. and contributors.
+ * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
+ */
+
+plugins {
+    id("kotlin")
+    id("me.champeau.jmh")
+}
+
+
+val mainJavaToolchainVersion by ext(project.property("java.mainToolchainVersion"))
+val modularJavaToolchainVersion by ext(project.property("java.modularToolchainVersion"))
+
+sourceSets {
+    dependencies {
+        implementation(project(":kotlinx-datetime"))
+        implementation("org.openjdk.jmh:jmh-core:1.35")
+    }
+}
+
+// Publish benchmarks to the root for the easier 'java -jar benchmarks.jar`
+tasks.named<Jar>("jmhJar") {
+    val nullString: String? = null
+    archiveBaseName.set("benchmarks")
+    archiveClassifier.set(nullString)
+    archiveVersion.set(nullString)
+    archiveVersion.convention(nullString)
+    destinationDirectory.set(file("$rootDir"))
+}
+
+repositories {
+    mavenCentral()
+}

benchmarks/src/jmh/kotlin/FormattingBenchmark.kt

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2019-2023 JetBrains s.r.o. and contributors.
+ * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
+ */
+
+package kotlinx.datetime
+
+import org.openjdk.jmh.annotations.*
+import java.util.concurrent.*
+
+@Warmup(iterations = 5, time = 1)
+@Measurement(iterations = 5, time = 1)
+@BenchmarkMode(Mode.Throughput)
+@OutputTimeUnit(TimeUnit.MICROSECONDS)
+@State(Scope.Benchmark)
+@Fork(1)
+open class FormattingBenchmark {
+
+    private val localDateTime = LocalDateTime(2023, 11, 9, 12, 21, 31, 41)
+    private val formatted = LocalDateTime.Formats.ISO.format(localDateTime)
+
+    @Benchmark
+    fun formatIso() = LocalDateTime.Formats.ISO.format(localDateTime)
+
+    @Benchmark
+    fun parseIso() = LocalDateTime.Formats.ISO.parse(formatted)
+}

gradle.properties

@@ -8,6 +8,7 @@ versionSuffix=SNAPSHOT
 defaultKotlinVersion=1.9.21
 dokkaVersion=1.9.10
 serializationVersion=1.6.2
+benchmarksVersion=0.7.2
 
 java.mainToolchainVersion=8
 java.modularToolchainVersion=11

settings.gradle.kts

@@ -5,8 +5,10 @@ pluginManagement {
         gradlePluginPortal()
     }
     val dokkaVersion: String by settings
+    val benchmarksVersion: String by settings
     plugins {
         id("org.jetbrains.dokka") version dokkaVersion
+        id("me.champeau.jmh") version benchmarksVersion
     }
 }
 
@@ -16,3 +18,5 @@ include(":core")
 project(":core").name = "kotlinx-datetime"
 include(":serialization")
 project(":serialization").name = "kotlinx-datetime-serialization"
+include(":benchmarks")
+