Comment benchmark methods

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/Add.kt

@@ -26,11 +26,27 @@ open class Add {
     @Param(BM_1, BM_10, BM_100, BM_1000, BM_10000, BM_100000, BM_1000000, BM_10000000)
     var size: Int = 0
 
+    /**
+     * Adds [size] elements to an empty persistent list.
+     *
+     * Measures mean time and memory spent per `add` operation.
+     *
+     * Expected time: nearly constant.
+     * Expected memory: for size in 1..32 - O(size), nearly constant otherwise.
+     */
     @Benchmark
     fun addLast(): ImmutableList<String> {
         return persistentListAdd(size)
     }
 
+    /**
+     * Adds [size] elements to an empty persistent list and then iterates all elements from first to last.
+     *
+     * Measures mean time and memory spent per `add` and `next` operations.
+     *
+     * Expected time: [addLast] + [Iterate.firstToLast]
+     * Expected memory: [addLast] + [Iterate.firstToLast]
+     */
     @Benchmark
     fun addLastAndIterate(bh: Blackhole) {
         val list = persistentListAdd(size)
@@ -39,6 +55,14 @@ open class Add {
         }
     }
 
+    /**
+     * Adds [size] elements to an empty persistent list and then gets all elements by index from first to last.
+     *
+     * Measures mean time and memory spent per `add` and `get` operations.
+     *
+     * Expected time: [addLast] + [Get.getByIndex]
+     * Expected memory: [addLast] + [Get.getByIndex]
+     */
     @Benchmark
     fun addLastAndGet(bh: Blackhole) {
         val list = persistentListAdd(size)

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/Get.kt

@@ -34,6 +34,14 @@ open class Get {
         persistentList = persistentListAdd(size)
     }
 
+    /**
+     * Gets every element by index starting from first to last.
+     *
+     * Measures mean time and memory spent per `get` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: none
+     */
     @Benchmark
     fun getByIndex(bh: Blackhole) {
         for (i in 0 until persistentList.size) {

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/Iterate.kt

@@ -34,13 +34,29 @@ open class Iterate {
         persistentList = persistentListAdd(size)
     }
 
+    /**
+     * Iterates every element starting from first to last.
+     *
+     * Measures mean time and memory spent per `next` operation.
+     *
+     * Expected time: nearly constant
+     * Expected memory: none once iterator created
+     */
     @Benchmark
     fun firstToLast(bh: Blackhole) {
         for (e in persistentList) {
             bh.consume(e)
         }
     }
 
+    /**
+     * Iterates every element starting from last to first.
+     *
+     * Measures mean time and memory spent per `previous` operation.
+     *
+     * Expected time: nearly constant
+     * Expected memory: none once iterator created
+     */
     @Benchmark
     fun lastToFirst(bh: Blackhole) {
         val iterator = persistentList.listIterator(size)

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/Remove.kt

@@ -34,6 +34,14 @@ open class Remove {
         persistentList = persistentListAdd(size)
     }
 
+    /**
+     * Removes all elements by index starting from last to first.
+     *
+     * Measures mean time and memory spent per `removeAt` operation.
+     *
+     * Expected time: nearly constant.
+     * Expected memory: for size in 1..32 - O(size), nearly constant otherwise.
+     */
     @Benchmark
     fun removeLast(): ImmutableList<String> {
         var list = persistentList

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/Set.kt

@@ -36,6 +36,14 @@ open class Set {
         randomIndices = List(size) { it }.shuffled()
     }
 
+    /**
+     * Updates each element by index starting from first to last.
+     *
+     * Measures mean time and memory spent per `set` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: logarithmic
+     */
     @Benchmark
     fun setByIndex(): ImmutableList<String> {
         repeat(times = size) { index ->
@@ -44,6 +52,14 @@ open class Set {
         return persistentList
     }
 
+    /**
+     * Updates each element by index randomly.
+     *
+     * Measures mean time and memory spent per `set` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: logarithmic
+     */
     @Benchmark
     fun setByRandomIndex(): ImmutableList<String> {
         repeat(times = size) { index ->

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/builder/Add.kt

@@ -29,11 +29,27 @@ open class Add {
     @Param(IP_100, IP_99_09, IP_95, IP_70, IP_50, IP_30, IP_0)
     var immutablePercentage: Double = 0.0
 
+    /**
+     * Adds [size] elements to an empty persistent list builder.
+     *
+     * Measures mean time and memory spent per `add` operation.
+     *
+     * Expected time: nearly constant.
+     * Expected memory: nearly constant.
+     */
     @Benchmark
     fun addLast(): PersistentList.Builder<String> {
         return persistentListBuilderAdd(size, immutablePercentage)
     }
 
+    /**
+     * Adds [size] elements to an empty persistent list builder and then iterates all elements from first to last.
+     *
+     * Measures mean time and memory spent per `add` and `next` operations.
+     *
+     * Expected time: [addLast] + [Iterate.firstToLast]
+     * Expected memory: [addLast] + [Iterate.firstToLast]
+     */
     @Benchmark
     fun addLastAndIterate(bh: Blackhole) {
         val builder = persistentListBuilderAdd(size, immutablePercentage)
@@ -42,6 +58,14 @@ open class Add {
         }
     }
 
+    /**
+     * Adds [size] elements to an empty persistent list builder and then gets all elements by index from first to last.
+     *
+     * Measures mean time and memory spent per `add` and `get` operations.
+     *
+     * Expected time: [addLast] + [Get.getByIndex]
+     * Expected memory: [addLast] + [Get.getByIndex]
+     */
     @Benchmark
     fun addLastAndGet(bh: Blackhole) {
         val builder = persistentListBuilderAdd(size, immutablePercentage)

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/builder/Get.kt

@@ -36,6 +36,14 @@ open class Get {
         builder = persistentListBuilderAdd(size, immutablePercentage)
     }
 
+    /**
+     * Gets every element by index starting from first to last.
+     *
+     * Measures mean time and memory spent per `get` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: none
+     */
     @Benchmark
     fun getByIndex(bh: Blackhole) {
         for (i in 0 until builder.size) {

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/builder/Iterate.kt

@@ -36,13 +36,29 @@ open class Iterate {
         builder = persistentListBuilderAdd(size, immutablePercentage)
     }
 
+    /**
+     * Iterates every element starting from first to last.
+     *
+     * Measures mean time and memory spent per `next` operation.
+     *
+     * Expected time: nearly constant
+     * Expected memory: none once iterator created
+     */
     @Benchmark
     fun firstToLast(bh: Blackhole) {
         for (e in builder) {
             bh.consume(e)
         }
     }
 
+    /**
+     * Iterates every element starting from last to first.
+     *
+     * Measures mean time and memory spent per `previous` operation.
+     *
+     * Expected time: nearly constant
+     * Expected memory: none once iterator created
+     */
     @Benchmark
     fun lastToFirst(bh: Blackhole) {
         val iterator = builder.listIterator(size)

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/builder/Remove.kt

@@ -28,6 +28,14 @@ open class Remove {
     @Param(IP_100, IP_99_09, IP_95, IP_70, IP_50, IP_30, IP_0)
     var immutablePercentage: Double = 0.0
 
+    /**
+     * Adds [size] elements to an empty persistent list builder and then removes each element by index starting from last to first.
+     *
+     * Measures mean time and memory spent per `add` and `removeAt` operations.
+     *
+     * Expected time: [Add.addLast] + nearly constant.
+     * Expected memory: [Add.addLast] + nearly constant.
+     */
     @Benchmark
     fun addAndRemoveLast(): PersistentList.Builder<String> {
         val builder = persistentListBuilderAdd(size, immutablePercentage)

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableList/builder/Set.kt

@@ -38,6 +38,14 @@ open class Set {
         randomIndices = List(size) { it }.shuffled()
     }
 
+    /**
+     * Updates each element by index starting from first to last.
+     *
+     * Measures mean time and memory spent per `set` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: nearly constant
+     */
     @Benchmark
     fun setByIndex(): PersistentList.Builder<String> {
         for (i in 0 until size) {
@@ -46,6 +54,14 @@ open class Set {
         return builder
     }
 
+    /**
+     * Updates each element by index randomly.
+     *
+     * Measures mean time and memory spent per `set` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: nearly constant
+     */
     @Benchmark
     fun setByRandomIndex(): PersistentList.Builder<String> {
         for (i in 0 until size) {

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableMap/Get.kt

@@ -44,6 +44,14 @@ open class Get {
             keys = generateKeys(hashCodeType, size)
     }
 
+    /**
+     * Gets every value by key.
+     *
+     * Measures mean time and memory spent per `get` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: none
+     */
     @Benchmark
     fun get(bh: Blackhole) {
         repeat(times = size) { index ->

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableMap/Iterate.kt

@@ -39,20 +39,44 @@ open class Iterate {
         persistentMap = persistentMapPut(implementation, generateKeys(hashCodeType, size))
     }
 
+    /**
+     * Iterates all keys.
+     *
+     * Measures mean time and memory spent per `next` operation.
+     *
+     * Expected time: nearly constant (logarithmic for ordered persistent map)
+     * Expected memory: none once iterator is created.
+     */
     @Benchmark
     fun iterateKeys(bh: Blackhole) {
         for (k in persistentMap.keys) {
             bh.consume(k)
         }
     }
 
+    /**
+     * Iterates all values.
+     *
+     * Measures mean time and memory spent per `next` operation.
+     *
+     * Expected time: nearly constant (logarithmic for ordered persistent map)
+     * Expected memory: none once iterator is created.
+     */
     @Benchmark
     fun iterateValues(bh: Blackhole) {
         for (v in persistentMap.values) {
             bh.consume(v)
         }
     }
 
+    /**
+     * Iterates all entries.
+     *
+     * Measures mean time and memory spent per `next` operation.
+     *
+     * Expected time: nearly constant (logarithmic for ordered persistent map)
+     * Expected memory: constant.
+     */
     @Benchmark
     fun iterateEntries(bh: Blackhole) {
         for (e in persistentMap) {

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableMap/Put.kt

@@ -39,11 +39,27 @@ open class Put {
         keys = generateKeys(hashCodeType, size)
     }
 
+    /**
+     * Adds [size] entries to an empty persistent map.
+     *
+     * Measures mean time and memory spent per `put` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: logarithmic
+     */
     @Benchmark
     fun put(): PersistentMap<IntWrapper, String> {
         return persistentMapPut(implementation, keys)
     }
 
+    /**
+     * Adds [size] entries to an empty persistent map and then gets every value by key.
+     *
+     * Measures mean time and memory spent per `put` and `get` operations.
+     *
+     * Expected time: [put] + [Get.get]
+     * Expected memory: [put] + [Get.get]
+     */
     @Benchmark
     fun putAndGet(bh: Blackhole) {
         val map = persistentMapPut(implementation, keys)
@@ -52,6 +68,14 @@ open class Put {
         }
     }
 
+    /**
+     * Adds [size] entries to an empty persistent map and then iterates all keys.
+     *
+     * Measures mean time and memory spent per `put` and `next` operations.
+     *
+     * Expected time: [put] + [Iterate.iterateKeys]
+     * Expected memory: [put] + [Iterate.iterateKeys]
+     */
     @Benchmark
     fun putAndIterateKeys(bh: Blackhole) {
         val map = persistentMapPut(implementation, keys)

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableMap/Remove.kt

@@ -44,6 +44,14 @@ open class Remove {
             keys = generateKeys(hashCodeType, size)
     }
 
+    /**
+     * Removes each entry by key.
+     *
+     * Measures mean time and memory spent per `remove` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: logarithmic
+     */
     @Benchmark
     fun remove(): PersistentMap<IntWrapper, String> {
         var map = persistentMap

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableMap/builder/Get.kt

@@ -47,6 +47,14 @@ open class Get {
             keys = generateKeys(hashCodeType, size)
     }
 
+    /**
+     * Gets every value by key.
+     *
+     * Measures mean time and memory spent per `get` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: none
+     */
     @Benchmark
     fun get(bh: Blackhole) {
         repeat(times = size) { index ->

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableMap/builder/Iterate.kt

@@ -43,20 +43,44 @@ open class Iterate {
         builder = persistentMapBuilderPut(implementation, keys, immutablePercentage)
     }
 
+    /**
+     * Iterates all keys.
+     *
+     * Measures mean time and memory spent per `next` operation.
+     *
+     * Expected time: nearly constant (logarithmic for ordered persistent map)
+     * Expected memory: none once iterator is created.
+     */
     @Benchmark
     fun iterateKeys(bh: Blackhole) {
         for (k in builder.keys) {
             bh.consume(k)
         }
     }
 
+    /**
+     * Iterates all values.
+     *
+     * Measures mean time and memory spent per `next` operation.
+     *
+     * Expected time: nearly constant (logarithmic for ordered persistent map)
+     * Expected memory: constant.
+     */
     @Benchmark
     fun iterateValues(bh: Blackhole) {
         for (v in builder.values) {
             bh.consume(v)
         }
     }
 
+    /**
+     * Iterates all entries.
+     *
+     * Measures mean time and memory spent per `next` operation.
+     *
+     * Expected time: nearly constant (logarithmic for ordered persistent map)
+     * Expected memory: constant.
+     */
     @Benchmark
     fun iterateEntries(bh: Blackhole) {
         for (e in builder) {

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableMap/builder/Put.kt

@@ -42,11 +42,27 @@ open class Put {
         keys = generateKeys(hashCodeType, size)
     }
 
+    /**
+     * Adds [size] entries to an empty persistent map builder.
+     *
+     * Measures mean time and memory spent per `put` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: logarithmic
+     */
     @Benchmark
     fun put(): PersistentMap.Builder<IntWrapper, String> {
         return persistentMapBuilderPut(implementation, keys, immutablePercentage)
     }
 
+    /**
+     * Adds [size] entries to an empty persistent map builder and then gets every value by key.
+     *
+     * Measures mean time and memory spent per `put` and `get` operations.
+     *
+     * Expected time: [put] + [Get.get]
+     * Expected memory: [put] + [Get.get]
+     */
     @Benchmark
     fun putAndGet(bh: Blackhole) {
         val builder = persistentMapBuilderPut(implementation, keys, immutablePercentage)
@@ -55,6 +71,14 @@ open class Put {
         }
     }
 
+    /**
+     * Adds [size] entries to an empty persistent map builder and then iterates all keys.
+     *
+     * Measures mean time and memory spent per `put` and `next` operations.
+     *
+     * Expected time: [put] + [Iterate.iterateKeys]
+     * Expected memory: [put] + [Iterate.iterateKeys]
+     */
     @Benchmark
     fun putAndIterateKeys(bh: Blackhole) {
         val builder = persistentMapBuilderPut(implementation, keys, immutablePercentage)

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableMap/builder/Remove.kt

@@ -48,6 +48,14 @@ open class Remove {
         }
     }
 
+    /**
+     * Adds [size] entries to an empty persistent map builder and then removes each entry by key.
+     *
+     * Measures mean time and memory spent per `put` and `remove` operations.
+     *
+     * Expected time: [Put.put] + logarithmic
+     * Expected memory: [Put.put] + logarithmic
+     */
     // Q: Why not to benchmark pure remove method?
     // A: Each invocation of remove benchmark method would clear the builder and creating new one would be needed each time.
     // Setting `@Setup(Level.Invocation)` may cause bad benchmark accuracy amid frequent `prepare` calls, especially for small `size`.

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableSet/Add.kt

@@ -39,11 +39,27 @@ open class Add {
         elements = generateElements(hashCodeType, size)
     }
 
+    /**
+     * Adds [size] elements to an empty persistent set.
+     *
+     * Measures mean time and memory spent per `add` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: logarithmic
+     */
     @Benchmark
     fun add(): ImmutableSet<IntWrapper> {
         return persistentSetAdd(implementation, elements)
     }
 
+    /**
+     * Adds [size] elements to an empty persistent set and then requests if every element is contained.
+     *
+     * Measures mean time and memory spent per `add` and `contains` operations.
+     *
+     * Expected time: [add] + [Contains.contains]
+     * Expected memory: [add] + [Contains.contains]
+     */
     @Benchmark
     fun addAndContains(bh: Blackhole) {
         val set = persistentSetAdd(implementation, elements)
@@ -52,6 +68,14 @@ open class Add {
         }
     }
 
+    /**
+     * Adds [size] elements to an empty persistent set and then iterates all elements.
+     *
+     * Measures mean time and memory spent per `add` and `next` operations.
+     *
+     * Expected time: [add] + [Iterate.iterate]
+     * Expected memory: [add] + [Iterate.iterate]
+     */
     @Benchmark
     fun addAndIterate(bh: Blackhole) {
         val set = persistentSetAdd(implementation, elements)

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableSet/Contains.kt

@@ -44,6 +44,14 @@ open class Contains {
             elements = generateElements(hashCodeType, size)
     }
 
+    /**
+     * Requests if every element is contained.
+     *
+     * Measures mean time and memory spent per `contains` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: none
+     */
     @Benchmark
     fun contains(bh: Blackhole) {
         repeat(times = size) { index ->

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableSet/Iterate.kt

@@ -39,6 +39,14 @@ open class Iterate {
         persistentSet = persistentSetAdd(implementation, generateElements(hashCodeType, size))
     }
 
+    /**
+     * Iterates all elements.
+     *
+     * Measures mean time and memory spent per `next` operation.
+     *
+     * Expected time: nearly constant (logarithmic for ordered persistent map)
+     * Expected memory: none once iterator is created.
+     */
     @Benchmark
     fun iterate(bh: Blackhole) {
         for (e in persistentSet) {

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableSet/Remove.kt

@@ -44,6 +44,14 @@ open class Remove {
             elements = generateElements(hashCodeType, size)
     }
 
+    /**
+     * Removes each element.
+     *
+     * Measures mean time and memory spent per `remove` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: logarithmic
+     */
     @Benchmark
     fun remove(): ImmutableSet<IntWrapper> {
         var set = persistentSet

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableSet/builder/Add.kt

@@ -42,11 +42,27 @@ open class Add {
         elements = generateElements(hashCodeType, size)
     }
 
+    /**
+     * Adds [size] elements to an empty persistent set builder.
+     *
+     * Measures mean time and memory spent per `add` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: logarithmic
+     */
     @Benchmark
     fun add(): PersistentSet.Builder<IntWrapper> {
         return persistentSetBuilderAdd(implementation, elements, immutablePercentage)
     }
 
+    /**
+     * Adds [size] elements to an empty persistent set builder and then requests if every element is contained.
+     *
+     * Measures mean time and memory spent per `add` and `contains` operations.
+     *
+     * Expected time: [add] + [Contains.contains]
+     * Expected memory: [add] + [Contains.contains]
+     */
     @Benchmark
     fun addAndContains(bh: Blackhole) {
         val builder = persistentSetBuilderAdd(implementation, elements, immutablePercentage)
@@ -55,6 +71,14 @@ open class Add {
         }
     }
 
+    /**
+     * Adds [size] elements to an empty persistent set builder and then iterates all elements.
+     *
+     * Measures mean time and memory spent per `add` and `next` operations.
+     *
+     * Expected time: [add] + [Iterate.iterate]
+     * Expected memory: [add] + [Iterate.iterate]
+     */
     @Benchmark
     fun addAndIterate(bh: Blackhole) {
         val set = persistentSetBuilderAdd(implementation, elements, immutablePercentage)

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableSet/builder/Contains.kt

@@ -47,6 +47,14 @@ open class Contains {
             elements = generateElements(hashCodeType, size)
     }
 
+    /**
+     * Requests if every element is contained.
+     *
+     * Measures mean time and memory spent per `contains` operation.
+     *
+     * Expected time: logarithmic
+     * Expected memory: none
+     */
     @Benchmark
     fun contains(bh: Blackhole) {
         repeat(times = size) { index ->

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableSet/builder/Iterate.kt

@@ -43,6 +43,14 @@ open class Iterate {
         builder = persistentSetBuilderAdd(implementation, elements, immutablePercentage)
     }
 
+    /**
+     * Iterates all elements.
+     *
+     * Measures mean time and memory spent per `next` operation.
+     *
+     * Expected time: nearly constant (logarithmic for ordered persistent map)
+     * Expected memory: none once iterator is created.
+     */
     @Benchmark
     fun iterate(bh: Blackhole) {
         for (e in builder) {

benchmarks-mpp/src/jvmMain/kotlin/benchmarks/immutableSet/builder/Remove.kt

@@ -48,6 +48,14 @@ open class Remove {
         }
     }
 
+    /**
+     * Adds [size] elements to an empty persistent set builder and then removes each element.
+     *
+     * Measures mean time and memory spent per `add` and `remove` operations.
+     *
+     * Expected time: [Add.add] + logarithmic
+     * Expected memory: [Add.add] + logarithmic
+     */
     @Benchmark
     fun addAndRemove(): PersistentSet.Builder<IntWrapper> {
         val builder = persistentSetBuilderAdd(implementation, elements, immutablePercentage)