Add NativeMemoryMap.hottestKeys, NativeMemoryMap.coldestKeys.

examples/map/offheap-eviction/src/main/kotlin/com/target/nativememoryallocator/examples/map/offheap.eviction/OffHeapEviction.kt

@@ -68,6 +68,8 @@ private class OffHeapEviction {
 
         logger.info { "nativeMemoryMap.size = ${nativeMemoryMap.size}" }
         logger.info { "nativeMemoryAllocator.nativeMemoryAllocatorMetadata = ${nativeMemoryAllocator.nativeMemoryAllocatorMetadata}" }
+        logger.info { "nativeMemoryMap.hottestKeys(10) = ${nativeMemoryMap.hottestKeys(numKeys = 10)}" }
+        logger.info { "nativeMemoryMap.coldestKeys(10) = ${nativeMemoryMap.coldestKeys(numKeys = 10)}" }
 
         val randomIndexValue = nativeMemoryMap.get(key = randomIndex)
         randomIndexValue?.let {

src/main/kotlin/com/target/nativememoryallocator/map/NativeMemoryMap.kt

@@ -99,6 +99,28 @@ interface NativeMemoryMap<KEY_TYPE : Any, VALUE_TYPE : Any> : BaseNativeMemoryMa
      * @return [Set] of [Map.Entry] for the map
      */
     val entries: Set<Map.Entry<KEY_TYPE, NativeMemoryBufferMetadata>>
+
+    /**
+     * [Set] of most-used keys in the map.
+     *
+     * This will only work if [NativeMemoryMapBackend.CAFFEINE] is used,
+     * and caffeine is configured with maximumSize eviction policy.
+     *
+     * @param numKeys number of keys to return
+     * @return [Set] of hottest [KEY_TYPE] keys
+     */
+    fun hottestKeys(numKeys: Int): Set<KEY_TYPE>
+
+    /**
+     * [Set] of least-used keys in the map.
+     *
+     * This will only work if [NativeMemoryMapBackend.CAFFEINE] is used,
+     * and caffeine is configured with maximumSize eviction policy.
+     *
+     * @param numKeys number of keys to return
+     * @return [Set] of coldest [KEY_TYPE] keys
+     */
+    fun coldestKeys(numKeys: Int): Set<KEY_TYPE>
 }
 
 /**

src/main/kotlin/com/target/nativememoryallocator/map/impl/CaffeineNativeMemoryMapImpl.kt

@@ -115,4 +115,18 @@ internal class CaffeineNativeMemoryMapImpl<KEY_TYPE : Any, VALUE_TYPE : Any>(
             caffeineStats = caffeineCache.stats(),
         )
 
+    /**
+     * Override hottestKeys to use caffeine eviction policy.
+     */
+    override fun hottestKeys(numKeys: Int): Set<KEY_TYPE> {
+        return caffeineCache.policy().eviction().map { it.hottest(numKeys).keys }.orElse(mutableSetOf())
+    }
+
+    /**
+     * Override coldestKeys to use caffeine eviction policy.
+     */
+    override fun coldestKeys(numKeys: Int): Set<KEY_TYPE> {
+        return caffeineCache.policy().eviction().map { it.coldest(numKeys).keys }.orElse(mutableSetOf())
+    }
+
 }

src/main/kotlin/com/target/nativememoryallocator/map/impl/NativeMemoryMapImpl.kt

@@ -140,4 +140,8 @@ internal class NativeMemoryMapImpl<KEY_TYPE : Any, VALUE_TYPE : Any>(
 
     override val operationCounters: NativeMemoryMapOperationCounters? = null
 
+    override fun hottestKeys(numKeys: Int): Set<KEY_TYPE> = emptySet()
+
+    override fun coldestKeys(numKeys: Int): Set<KEY_TYPE> = emptySet()
+
 }