From 6dde47d4180501cf1723a60265cf02960b20b922 Mon Sep 17 00:00:00 2001
From: "Aaron.Riekenberg" <aaron.riekenberg@target.com>
Date: Fri, 8 Mar 2024 14:48:11 -0600
Subject: [PATCH] Add NativeMemoryMap.hottestKeys, NativeMemoryMap.coldestKeys.

---
 .../map/offheap.eviction/OffHeapEviction.kt   |  2 ++
 .../map/NativeMemoryMap.kt                    | 22 +++++++++++++++++++
 .../map/impl/CaffeineNativeMemoryMapImpl.kt   | 14 ++++++++++++
 .../map/impl/NativeMemoryMapImpl.kt           |  4 ++++
 4 files changed, 42 insertions(+)

diff --git a/examples/map/offheap-eviction/src/main/kotlin/com/target/nativememoryallocator/examples/map/offheap.eviction/OffHeapEviction.kt b/examples/map/offheap-eviction/src/main/kotlin/com/target/nativememoryallocator/examples/map/offheap.eviction/OffHeapEviction.kt
index 2fac626..900e892 100644
--- a/examples/map/offheap-eviction/src/main/kotlin/com/target/nativememoryallocator/examples/map/offheap.eviction/OffHeapEviction.kt
+++ b/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 {
diff --git a/src/main/kotlin/com/target/nativememoryallocator/map/NativeMemoryMap.kt b/src/main/kotlin/com/target/nativememoryallocator/map/NativeMemoryMap.kt
index 27df6e2..fdae1e9 100644
--- a/src/main/kotlin/com/target/nativememoryallocator/map/NativeMemoryMap.kt
+++ b/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>
 }
 
 /**
diff --git a/src/main/kotlin/com/target/nativememoryallocator/map/impl/CaffeineNativeMemoryMapImpl.kt b/src/main/kotlin/com/target/nativememoryallocator/map/impl/CaffeineNativeMemoryMapImpl.kt
index 6a721b7..32a9bfc 100644
--- a/src/main/kotlin/com/target/nativememoryallocator/map/impl/CaffeineNativeMemoryMapImpl.kt
+++ b/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())
+    }
+
 }
\ No newline at end of file
diff --git a/src/main/kotlin/com/target/nativememoryallocator/map/impl/NativeMemoryMapImpl.kt b/src/main/kotlin/com/target/nativememoryallocator/map/impl/NativeMemoryMapImpl.kt
index fb98b1d..476b697 100644
--- a/src/main/kotlin/com/target/nativememoryallocator/map/impl/NativeMemoryMapImpl.kt
+++ b/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()
+
 }
\ No newline at end of file