Add clarifying comments for halfHeightPersistentMap/Set

Author: Abduqodiri Qurbonzoda

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

@@ -24,6 +24,11 @@ open class Remove {
 
     private var keys = listOf<IntWrapper>()
     private var persistentMap = persistentMapOf<IntWrapper, String>()
+
+    /**
+     * Expected height of this persistent map is equal to the [persistentMap]'s expected height divided by 2.
+     * Obtained by removing some entries of the [persistentMap].
+     */
     private var halfHeightPersistentMap = persistentMapOf<IntWrapper, String>()
 
     @Setup(Level.Trial)
@@ -46,8 +51,7 @@ open class Remove {
     }
 
     /**
-     * Puts `size - entriesForHalfHeight(size)` new entries to a persistent map of size `entriesForHalfHeight(size)`
-     * that had initially [size] entries.
+     * Puts `size - halfHeightPersistentMap.size` new entries to the [Remove.halfHeightPersistentMap].
      *
      * Measures mean time and memory spent per (roughly one) `put` operation.
      *
@@ -59,19 +63,19 @@ open class Remove {
         var map = halfHeightPersistentMap
 
         repeat(size - halfHeightPersistentMap.size) { index ->
-            map = map.put(keys[index], "some element")
+            map = map.put(keys[index], "new value")
         }
 
         return map
     }
 
     /**
-     * Iterates keys of a persistent map of size `entriesForHalfHeight(size)` several times until iterating [size] elements.
+     * Iterates keys of the [Remove.halfHeightPersistentMap] several times until iterating [size] elements.
      *
      * Measures mean time and memory spent per `iterate` operation.
      *
-     * Expected time: [Iterate.iterateKeys] with [Iterate.size] = `entriesForHalfHeight([size])`
-     * Expected memory: [Iterate.iterateKeys] with [Iterate.size] = `entriesForHalfHeight([size])`
+     * Expected time: [Iterate.iterateKeys] with [Iterate.size] = `halfHeightPersistentMap.size`
+     * Expected memory: [Iterate.iterateKeys] with [Iterate.size] = `halfHeightPersistentMap.size`
      */
     @Benchmark
     fun iterateKeysAfterRemove(bh: Blackhole) {

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

@@ -19,12 +19,12 @@ fun persistentMapBuilderPut(
 
     var map = emptyPersistentMap<IntWrapper, String>(implementation)
     for (index in 0 until immutableSize) {
-        map = map.put(keys[index], "some element")
+        map = map.put(keys[index], "some value")
     }
 
     val builder = map.builder()
     for (index in immutableSize until keys.size) {
-        builder[keys[index]] = "some element"
+        builder[keys[index]] = "some value"
     }
 
     return builder

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

@@ -22,26 +22,44 @@ fun <K, V> emptyPersistentMap(implementation: String): PersistentMap<K, V> = whe
 fun <K> persistentMapPut(implementation: String, keys: List<K>): PersistentMap<K, String> {
     var map = emptyPersistentMap<K, String>(implementation)
     for (key in keys) {
-        map = map.put(key, "some element")
+        map = map.put(key, "some value")
     }
     return map
 }
 
-private fun entriesForHalfHeight(size: Int): Int {
-    val branchingFactor = 32
-    val logBranchingFactor = 5
 
-    val approximateHeight = ceil(log(size.toDouble(), branchingFactor.toDouble())).toInt()
-    return 1 shl ((approximateHeight / 2) * logBranchingFactor)
+private const val branchingFactor = 32
+private const val logBranchingFactor = 5
+
+private fun expectedHeightOfPersistentMapWithSize(size: Int): Int {
+    return ceil(log(size.toDouble(), branchingFactor.toDouble())).toInt()
 }
 
+/**
+ * Returns the size of a persistent map whose expected height is
+ * half of the specified [persistentMap]'s expected height.
+ */
+private fun sizeForHalfHeight(persistentMap: PersistentMap<*, *>): Int {
+    val expectedHeight = expectedHeightOfPersistentMapWithSize(persistentMap.size)
+    return 1 shl ((expectedHeight / 2) * logBranchingFactor)
+}
 
+/**
+ * Returns a new persistent map by removing some entries of the specified [persistentMap].
+ * The expected height of the returned persistent map is half of the specified [persistentMap]'s expected height.
+ *
+ * If the specified [persistentMap] does not maintain its canonical form,
+ * after removing some entries its actual average height will become bigger then its expected height.
+ * Thus, many operations on the returned persistent map will be slower.
+ */
 fun <K> halfHeightPersistentMap(persistentMap: PersistentMap<K, String>, keys: List<K>): PersistentMap<K, String> {
-    val elementsToLeave = entriesForHalfHeight(persistentMap.size)
+    val entriesToLeave = sizeForHalfHeight(persistentMap)
+
+    val shuffledKeys = keys.shuffled()
 
     var map = persistentMap
-    repeat(persistentMap.size - elementsToLeave) { index ->
-        map = map.remove(keys[index])
+    repeat(persistentMap.size - entriesToLeave) { index ->
+        map = map.remove(shuffledKeys[index])
     }
     return map
 }

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

@@ -24,6 +24,11 @@ open class Remove {
 
     private var elements = listOf<IntWrapper>()
     private var persistentSet = persistentSetOf<IntWrapper>()
+
+    /**
+     * Expected height of this persistent set is equal to the [persistentSet]'s expected height divided by 2.
+     * Obtained by removing some elements of the [persistentSet].
+     */
     private var halfHeightPersistentSet = persistentSetOf<IntWrapper>()
 
     @Setup(Level.Trial)
@@ -46,8 +51,7 @@ open class Remove {
     }
 
     /**
-     * Adds `size - elementsForHalfHeight(size)` new elements to a persistent set of size `elementsForHalfHeight(size)`
-     * that had initially [size] elements.
+     * Adds `size - halfHeightPersistentSet.size` new elements to the [Remove.halfHeightPersistentSet].
      *
      * Measures mean time and memory spent per (roughly one) `add` operation.
      *
@@ -66,12 +70,12 @@ open class Remove {
     }
 
     /**
-     * Iterates elements of a persistent set of size `elementsForHalfHeight(size)` several times until iterating [size] elements.
+     * Iterates elements of the [Remove.halfHeightPersistentSet] several times until iterating [size] elements.
      *
      * Measures mean time and memory spent per `iterate` operation.
      *
-     * Expected time: [Iterate.iterate] with [Iterate.size] = `elementsForHalfHeight([size])`
-     * Expected memory: [Iterate.iterate] with [Iterate.size] = `elementsForHalfHeight([size])`
+     * Expected time: [Iterate.iterate] with [Iterate.size] = `halfHeightPersistentSet.size`
+     * Expected memory: [Iterate.iterate] with [Iterate.size] = `halfHeightPersistentSet.size`
      */
     @Benchmark
     fun iterateAfterRemove(bh: Blackhole) {

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

@@ -27,20 +27,38 @@ fun <E> persistentSetAdd(implementation: String, elements: List<E>): PersistentS
     return set
 }
 
-private fun elementsForHalfHeight(size: Int): Int {
-    val branchingFactor = 32
-    val logBranchingFactor = 5
+private const val branchingFactor = 32
+private const val logBranchingFactor = 5
 
-    val approximateHeight = ceil(log(size.toDouble(), branchingFactor.toDouble())).toInt()
-    return 1 shl ((approximateHeight / 2) * logBranchingFactor)
+private fun expectedHeightOfPersistentSetWithSize(size: Int): Int {
+    return ceil(log(size.toDouble(), branchingFactor.toDouble())).toInt()
 }
 
+/**
+ * Returns the size of a persistent set whose expected height is
+ * half of the specified [persistentSet]'s expected height.
+ */
+private fun sizeForHalfHeight(persistentSet: PersistentSet<*>): Int {
+    val expectedHeight = expectedHeightOfPersistentSetWithSize(persistentSet.size)
+    return 1 shl ((expectedHeight / 2) * logBranchingFactor)
+}
+
+/**
+ * Returns a new persistent set by removing some elements of the specified [persistentSet].
+ * The expected height of the returned persistent set is half of the specified [persistentSet]'s expected height.
+ *
+ * If the specified [persistentSet] does not maintain its canonical form,
+ * after removing some elements its actual average height will become bigger then its expected height.
+ * Thus, many operations on the returned persistent set will be slower.
+ */
 fun <E> halfHeightPersistentSet(persistentSet: PersistentSet<E>, elements: List<E>): PersistentSet<E> {
-    val elementsToLeave = elementsForHalfHeight(persistentSet.size)
+    val elementsToLeave = sizeForHalfHeight(persistentSet)
+
+    val shuffledElements = elements.shuffled()
 
     var set = persistentSet
     repeat(persistentSet.size - elementsToLeave) { index ->
-        set = set.remove(elements[index])
+        set = set.remove(shuffledElements[index])
     }
     return set
 }