From 4789a9ec18a213be20f04b7f02f3900ca7a566c2 Mon Sep 17 00:00:00 2001
From: Alex Peck <alexpeck@microsoft.com>
Date: Sat, 2 Dec 2023 14:47:00 -0800
Subject: [PATCH 01/11] generic node

---
 .../Lfu/ConcurrentLfuSoakTests.cs             |  24 +-
 BitFaster.Caching/Lfu/ConcurrentLfu.cs        | 211 ++++++++++++++++--
 BitFaster.Caching/Lfu/LfuNode.cs              |   9 +-
 BitFaster.Caching/Lfu/NodePolicy.cs           |  22 ++
 4 files changed, 231 insertions(+), 35 deletions(-)
 create mode 100644 BitFaster.Caching/Lfu/NodePolicy.cs

diff --git a/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuSoakTests.cs b/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuSoakTests.cs
index 86e0e075..6a24d833 100644
--- a/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuSoakTests.cs
+++ b/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuSoakTests.cs
@@ -310,11 +310,13 @@ private async Task RunIntegrityCheckAsync(ConcurrentLfu<int, string> lfu, int it
 
         private static void RunIntegrityCheck<K,V>(ConcurrentLfu<K,V> cache, ITestOutputHelper output)
         {
-            new ConcurrentLfuIntegrityChecker<K, V>(cache).Validate(output);
+            new ConcurrentLfuIntegrityChecker<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>>(cache).Validate(output);
         }
     }
 
-    public class ConcurrentLfuIntegrityChecker<K, V>
+    internal class ConcurrentLfuIntegrityChecker<K, V, N, P>
+        where N : LfuNode<K, V>
+        where P : struct, INodePolicy<K, V, N>
     {
         private readonly ConcurrentLfu<K, V> cache;
 
@@ -322,15 +324,15 @@ public class ConcurrentLfuIntegrityChecker<K, V>
         private readonly LfuNodeList<K, V> probationLru;
         private readonly LfuNodeList<K, V> protectedLru;
 
-        private readonly StripedMpscBuffer<LfuNode<K, V>> readBuffer;
-        private readonly MpscBoundedBuffer<LfuNode<K, V>> writeBuffer;
+        private readonly StripedMpscBuffer<N> readBuffer;
+        private readonly MpscBoundedBuffer<N> writeBuffer;
 
-        private static FieldInfo windowLruField = typeof(ConcurrentLfu<K, V>).GetField("windowLru", BindingFlags.NonPublic | BindingFlags.Instance);
-        private static FieldInfo probationLruField = typeof(ConcurrentLfu<K, V>).GetField("probationLru", BindingFlags.NonPublic | BindingFlags.Instance);
-        private static FieldInfo protectedLruField = typeof(ConcurrentLfu<K, V>).GetField("protectedLru", BindingFlags.NonPublic | BindingFlags.Instance);
+        private static FieldInfo windowLruField = typeof(ConcurrentLfuCore<K, V, N, P>).GetField("windowLru", BindingFlags.NonPublic | BindingFlags.Instance);
+        private static FieldInfo probationLruField = typeof(ConcurrentLfuCore<K, V, N, P>).GetField("probationLru", BindingFlags.NonPublic | BindingFlags.Instance);
+        private static FieldInfo protectedLruField = typeof(ConcurrentLfuCore<K, V, N, P>).GetField("protectedLru", BindingFlags.NonPublic | BindingFlags.Instance);
 
-        private static FieldInfo readBufferField = typeof(ConcurrentLfu<K, V>).GetField("readBuffer", BindingFlags.NonPublic | BindingFlags.Instance);
-        private static FieldInfo writeBufferField = typeof(ConcurrentLfu<K, V>).GetField("writeBuffer", BindingFlags.NonPublic | BindingFlags.Instance);
+        private static FieldInfo readBufferField = typeof(ConcurrentLfuCore<K, V, N, P>).GetField("readBuffer", BindingFlags.NonPublic | BindingFlags.Instance);
+        private static FieldInfo writeBufferField = typeof(ConcurrentLfuCore<K, V, N, P>).GetField("writeBuffer", BindingFlags.NonPublic | BindingFlags.Instance);
 
         public ConcurrentLfuIntegrityChecker(ConcurrentLfu<K, V> cache)
         {
@@ -341,8 +343,8 @@ public ConcurrentLfuIntegrityChecker(ConcurrentLfu<K, V> cache)
             this.probationLru = (LfuNodeList<K, V>)probationLruField.GetValue(cache);
             this.protectedLru = (LfuNodeList<K, V>)protectedLruField.GetValue(cache);
 
-            this.readBuffer = (StripedMpscBuffer<LfuNode<K, V>>)readBufferField.GetValue(cache);
-            this.writeBuffer = (MpscBoundedBuffer<LfuNode<K, V>>)writeBufferField.GetValue(cache);
+            this.readBuffer = (StripedMpscBuffer<N>)readBufferField.GetValue(cache);
+            this.writeBuffer = (MpscBoundedBuffer<N>)writeBufferField.GetValue(cache);
         }
 
         public void Validate(ITestOutputHelper output)
diff --git a/BitFaster.Caching/Lfu/ConcurrentLfu.cs b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
index 6f19e3fb..efb5511a 100644
--- a/BitFaster.Caching/Lfu/ConcurrentLfu.cs
+++ b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
@@ -20,6 +20,169 @@
 
 namespace BitFaster.Caching.Lfu
 {
+    /// <summary>
+    /// Facade to hide generics.
+    /// </summary>
+    public sealed class ConcurrentLfu<K, V> : ICache<K, V>, IAsyncCache<K, V>, IBoundedPolicy
+    {
+        private readonly ConcurrentLfuCore<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>> core;
+
+        /// <summary>
+        /// The default buffer size.
+        /// </summary>
+        public const int DefaultBufferSize = 128;
+
+        /// <summary>
+        /// Initializes a new instance of the ConcurrentLfu class with the specified capacity.
+        /// </summary>
+        /// <param name="capacity">The capacity.</param>
+        public ConcurrentLfu(int capacity)
+        {
+            this.core = new (capacity);
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the ConcurrentLfu class with the specified concurrencyLevel, capacity, scheduler, equality comparer and buffer size.
+        /// </summary>
+        /// <param name="concurrencyLevel">The concurrency level.</param>
+        /// <param name="capacity">The capacity.</param>
+        /// <param name="scheduler">The scheduler.</param>
+        /// <param name="comparer">The equality comparer.</param>
+        public ConcurrentLfu(int concurrencyLevel, int capacity, IScheduler scheduler, IEqualityComparer<K> comparer)
+        {
+            this.core = new (concurrencyLevel, capacity, scheduler, comparer);
+        }
+
+        ///<inheritdoc/>
+        public int Count => core.Count;
+
+        ///<inheritdoc/>
+        public Optional<ICacheMetrics> Metrics => core.Metrics;
+
+        ///<inheritdoc/>
+        public Optional<ICacheEvents<K, V>> Events => core.Events;
+
+        ///<inheritdoc/>
+        public CachePolicy Policy => core.Policy;
+
+        ///<inheritdoc/>
+        public ICollection<K> Keys => core.Keys;
+
+        ///<inheritdoc/>
+        public int Capacity => core.Capacity;
+
+        ///<inheritdoc/>
+        public IScheduler Scheduler => core.Scheduler;
+
+        /// <summary>
+        /// Synchronously perform all pending policy maintenance. Drain the read and write buffers then
+        /// use the eviction policy to preserve bounded size and remove expired items.
+        /// </summary>
+        /// <remarks>
+        /// Note: maintenance is automatically performed asynchronously immediately following a read or write.
+        /// It is not necessary to call this method, <see cref="DoMaintenance"/> is provided purely to enable tests to reach a consistent state.
+        /// </remarks>
+        public void DoMaintenance()
+        {
+            core.DoMaintenance();
+        }
+
+        ///<inheritdoc/>
+        public void AddOrUpdate(K key, V value)
+        {
+            core.AddOrUpdate(key, value);
+        }
+
+        ///<inheritdoc/>
+        public void Clear()
+        {
+            core.Clear();
+        }
+
+        ///<inheritdoc/>
+        public IEnumerator<KeyValuePair<K, V>> GetEnumerator()
+        {
+            return core.GetEnumerator();
+        }
+
+        ///<inheritdoc/>
+        public V GetOrAdd(K key, Func<K, V> valueFactory)
+        {
+            return core.GetOrAdd(key, valueFactory);
+        }
+
+        ///<inheritdoc/>
+        public V GetOrAdd<TArg>(K key, Func<K, TArg, V> valueFactory, TArg factoryArgument)
+        {
+            return core.GetOrAdd(key, valueFactory, factoryArgument);
+        }
+
+        ///<inheritdoc/>
+        public ValueTask<V> GetOrAddAsync(K key, Func<K, Task<V>> valueFactory)
+        {
+            return core.GetOrAddAsync(key, valueFactory);
+        }
+
+        ///<inheritdoc/>
+        public ValueTask<V> GetOrAddAsync<TArg>(K key, Func<K, TArg, Task<V>> valueFactory, TArg factoryArgument)
+        {
+            return core.GetOrAddAsync(key, valueFactory, factoryArgument);
+        }
+
+        ///<inheritdoc/>
+        public void Trim(int itemCount)
+        {
+            core.Trim(itemCount);
+        }
+
+        ///<inheritdoc/>
+        public bool TryGet(K key, out V value)
+        {
+            return core.TryGet(key, out value);
+        }
+
+        ///<inheritdoc/>
+        public bool TryRemove(K key)
+        {
+            return core.TryRemove(key);
+        }
+
+        ///<inheritdoc/>
+        public bool TryRemove(KeyValuePair<K, V> item)
+        {
+            return core.TryRemove(item);
+        }
+
+        ///<inheritdoc/>
+        public bool TryRemove(K key, out V value)
+        {
+            return core.TryRemove(key, out value);
+        }
+
+        ///<inheritdoc/>
+        public bool TryUpdate(K key, V value)
+        {
+            return core.TryUpdate(key, value);
+        }
+
+        ///<inheritdoc/>
+        IEnumerator IEnumerable.GetEnumerator()
+        {
+            return core.GetEnumerator();
+        }
+
+#if DEBUG
+        /// <summary>
+        /// Format the LFU as a string by converting all the keys to strings.
+        /// </summary>
+        /// <returns>The LFU formatted as a string.</returns>
+        public string FormatLfuString()
+        {
+            return core.FormatLfuString();
+        }
+#endif
+    }
+
     /// <summary>
     /// An approximate LFU based on the W-TinyLfu eviction policy. W-TinyLfu tracks items using a window LRU list, and 
     /// a main space LRU divided into protected and probation segments. Reads and writes to the cache are stored in buffers
@@ -40,9 +203,11 @@ namespace BitFaster.Caching.Lfu
     /// </summary>
     /// Based on the Caffeine library by ben.manes@gmail.com (Ben Manes).
     /// https://github.com/ben-manes/caffeine
-    [DebuggerTypeProxy(typeof(ConcurrentLfu<,>.LfuDebugView))]
+    [DebuggerTypeProxy(typeof(ConcurrentLfuCore<,,,>.LfuDebugView))]
     [DebuggerDisplay("Count = {Count}/{Capacity}")]
-    public sealed class ConcurrentLfu<K, V> : ICache<K, V>, IAsyncCache<K, V>, IBoundedPolicy
+    internal sealed class ConcurrentLfuCore<K, V, N, P> : ICache<K, V>, IAsyncCache<K, V>, IBoundedPolicy
+        where N : LfuNode<K, V>
+        where P : struct, INodePolicy<K, V, N>
     {
         private const int MaxWriteBufferRetries = 64;
 
@@ -51,10 +216,10 @@ public sealed class ConcurrentLfu<K, V> : ICache<K, V>, IAsyncCache<K, V>, IBoun
         /// </summary>
         public const int DefaultBufferSize = 128;
 
-        private readonly ConcurrentDictionary<K, LfuNode<K, V>> dictionary;
+        private readonly ConcurrentDictionary<K, N> dictionary;
 
-        private readonly StripedMpscBuffer<LfuNode<K, V>> readBuffer;
-        private readonly MpscBoundedBuffer<LfuNode<K, V>> writeBuffer;
+        private readonly StripedMpscBuffer<N> readBuffer;
+        private readonly MpscBoundedBuffer<N> writeBuffer;
 
         private readonly CacheMetrics metrics = new();
 
@@ -72,13 +237,13 @@ public sealed class ConcurrentLfu<K, V> : ICache<K, V>, IAsyncCache<K, V>, IBoun
         private readonly IScheduler scheduler;
         private readonly Action drainBuffers;
 
-        private readonly LfuNode<K, V>[] drainBuffer;
+        private readonly N[] drainBuffer;
 
         /// <summary>
         /// Initializes a new instance of the ConcurrentLfu class with the specified capacity.
         /// </summary>
         /// <param name="capacity">The capacity.</param>
-        public ConcurrentLfu(int capacity)
+        public ConcurrentLfuCore(int capacity)
             : this(Defaults.ConcurrencyLevel, capacity, new ThreadPoolScheduler(), EqualityComparer<K>.Default)
         {        
         }
@@ -90,18 +255,18 @@ public ConcurrentLfu(int capacity)
         /// <param name="capacity">The capacity.</param>
         /// <param name="scheduler">The scheduler.</param>
         /// <param name="comparer">The equality comparer.</param>
-        public ConcurrentLfu(int concurrencyLevel, int capacity, IScheduler scheduler, IEqualityComparer<K> comparer)
+        public ConcurrentLfuCore(int concurrencyLevel, int capacity, IScheduler scheduler, IEqualityComparer<K> comparer)
         {
             int dictionaryCapacity = ConcurrentDictionarySize.Estimate(capacity);
-            this.dictionary = new ConcurrentDictionary<K, LfuNode<K, V>>(concurrencyLevel, dictionaryCapacity, comparer);
+            this.dictionary = new (concurrencyLevel, dictionaryCapacity, comparer);
 
             // cap concurrency at proc count * 2
             int readStripes = Math.Min(BitOps.CeilingPowerOfTwo(concurrencyLevel), BitOps.CeilingPowerOfTwo(Environment.ProcessorCount * 2));
-            this.readBuffer = new StripedMpscBuffer<LfuNode<K, V>>(readStripes, DefaultBufferSize);
+            this.readBuffer = new (readStripes, DefaultBufferSize);
 
             // Cap the write buffer to the cache size, or 128. Whichever is smaller.
             int writeBufferSize = Math.Min(BitOps.CeilingPowerOfTwo(capacity), 128);
-            this.writeBuffer = new MpscBoundedBuffer<LfuNode<K, V>>(writeBufferSize);
+            this.writeBuffer = new (writeBufferSize);
 
             this.cmSketch = new CmSketch<K>(capacity, comparer);
             this.windowLru = new LfuNodeList<K, V>();
@@ -113,7 +278,7 @@ public ConcurrentLfu(int concurrencyLevel, int capacity, IScheduler scheduler, I
             this.scheduler = scheduler;
             this.drainBuffers = () => this.DrainBuffers();
 
-            this.drainBuffer = new LfuNode<K, V>[this.readBuffer.Capacity];
+            this.drainBuffer = new N[this.readBuffer.Capacity];
         }
 
         // No lock count: https://arbel.net/2013/02/03/best-practices-for-using-concurrentdictionary/
@@ -150,7 +315,7 @@ public void AddOrUpdate(K key, V value)
                     return;
                 }
 
-                var node = new LfuNode<K, V>(key, value);
+                var node = default(P).Create(key, value);
                 if (this.dictionary.TryAdd(key, node))
                 {
                     AfterWrite(node);
@@ -205,7 +370,7 @@ public void Trim(int itemCount)
 
         private bool TryAdd(K key, V value)
         {
-            var node = new LfuNode<K, V>(key, value);
+            var node = default(P).Create(key, value);
 
             if (this.dictionary.TryAdd(key, node))
             {
@@ -338,13 +503,13 @@ public bool TryRemove(KeyValuePair<K, V> item)
             {
                 if (EqualityComparer<V>.Default.Equals(node.Value, item.Value))
                 {
-                    var kvp = new KeyValuePair<K, LfuNode<K,V>>(item.Key, node);
+                    var kvp = new KeyValuePair<K, N>(item.Key, node);
 
 #if NET6_0_OR_GREATER
                     if (this.dictionary.TryRemove(kvp))
 #else
                     // https://devblogs.microsoft.com/pfxteam/little-known-gems-atomic-conditional-removals-from-concurrentdictionary/
-                    if (((ICollection<KeyValuePair<K, LfuNode<K, V>>>)this.dictionary).Remove(kvp))
+                    if (((ICollection<KeyValuePair<K, N>>)this.dictionary).Remove(kvp))
 #endif
                     {
                         node.WasRemoved = true;
@@ -445,7 +610,7 @@ private static void TakeCandidatesInLruOrder(LfuNodeList<K, V> lru, List<LfuNode
             }
         }
 
-        private void AfterWrite(LfuNode<K, V> node)
+        private void AfterWrite(N node)
         {
             for (int i = 0; i < MaxWriteBufferRetries; i++)
             {
@@ -509,7 +674,7 @@ private void ScheduleAfterWrite()
 
         IEnumerator IEnumerable.GetEnumerator()
         {
-            return ((ConcurrentLfu<K, V>)this).GetEnumerator();
+            return ((ConcurrentLfuCore<K, V, N, P>)this).GetEnumerator();
         }
 
         private void TryScheduleDrain()
@@ -570,7 +735,7 @@ private void DrainBuffers()
             }
         }
 
-        private bool Maintenance(LfuNode<K, V> droppedWrite = null)
+        private bool Maintenance(N droppedWrite = null)
         {
             this.drainStatus.VolatileWrite(DrainStatus.ProcessingToIdle);
 
@@ -975,9 +1140,9 @@ public string FormatLfuString()
         [ExcludeFromCodeCoverage]
         internal class LfuDebugView
         {
-            private readonly ConcurrentLfu<K, V> lfu;
+            private readonly ConcurrentLfuCore<K, V, N, P> lfu;
 
-            public LfuDebugView(ConcurrentLfu<K, V> lfu)
+            public LfuDebugView(ConcurrentLfuCore<K, V, N, P> lfu)
             {
                 this.lfu = lfu;
             }
@@ -986,9 +1151,9 @@ public LfuDebugView(ConcurrentLfu<K, V> lfu)
 
             public ICacheMetrics Metrics => lfu.metrics;
 
-            public StripedMpscBuffer<LfuNode<K, V>> ReadBuffer => this.lfu.readBuffer;
+            public StripedMpscBuffer<N> ReadBuffer => this.lfu.readBuffer;
 
-            public MpscBoundedBuffer<LfuNode<K, V>> WriteBuffer => this.lfu.writeBuffer;
+            public MpscBoundedBuffer<N> WriteBuffer => this.lfu.writeBuffer;
 
             public KeyValuePair<K, V>[] Items
             {
diff --git a/BitFaster.Caching/Lfu/LfuNode.cs b/BitFaster.Caching/Lfu/LfuNode.cs
index 40028176..f56db8e2 100644
--- a/BitFaster.Caching/Lfu/LfuNode.cs
+++ b/BitFaster.Caching/Lfu/LfuNode.cs
@@ -1,6 +1,6 @@
 namespace BitFaster.Caching.Lfu
 {
-    internal sealed class LfuNode<K, V>
+    internal class LfuNode<K, V>
     {
         internal LfuNodeList<K, V> list;
         internal LfuNode<K, V> next;
@@ -57,4 +57,11 @@ internal enum Position
         Probation,
         Protected,
     }
+
+    internal sealed class AccessOrderNode<K, V> : LfuNode<K, V>
+    {
+        public AccessOrderNode(K k, V v) : base(k, v)
+        {
+        }
+    }
 }
diff --git a/BitFaster.Caching/Lfu/NodePolicy.cs b/BitFaster.Caching/Lfu/NodePolicy.cs
new file mode 100644
index 00000000..5e3a21f8
--- /dev/null
+++ b/BitFaster.Caching/Lfu/NodePolicy.cs
@@ -0,0 +1,22 @@
+using System;
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+using System.Text;
+
+namespace BitFaster.Caching.Lfu
+{
+    internal interface INodePolicy<K, V, N>
+        where N : LfuNode<K, V>
+    {
+        N Create(K key, V value);
+    }
+
+    internal struct AccessOrderPolicy<K, V> : INodePolicy<K, V, AccessOrderNode<K, V>>
+    {
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public AccessOrderNode<K, V> Create(K key, V value)
+        {
+            return new AccessOrderNode<K, V>(key, value);
+        }
+    }
+}

From 5bf76ac8c555193a44af299320dbb423c8cce994 Mon Sep 17 00:00:00 2001
From: Alex Peck <alexpeck@microsoft.com>
Date: Sat, 2 Dec 2023 14:50:11 -0800
Subject: [PATCH 02/11] core

---
 BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuSoakTests.cs | 6 +++---
 BitFaster.Caching/Lfu/ConcurrentLfu.cs                    | 2 ++
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuSoakTests.cs b/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuSoakTests.cs
index 6a24d833..5fceb2ec 100644
--- a/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuSoakTests.cs
+++ b/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuSoakTests.cs
@@ -310,7 +310,7 @@ private async Task RunIntegrityCheckAsync(ConcurrentLfu<int, string> lfu, int it
 
         private static void RunIntegrityCheck<K,V>(ConcurrentLfu<K,V> cache, ITestOutputHelper output)
         {
-            new ConcurrentLfuIntegrityChecker<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>>(cache).Validate(output);
+            new ConcurrentLfuIntegrityChecker<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>>(cache.Core).Validate(output);
         }
     }
 
@@ -318,7 +318,7 @@ internal class ConcurrentLfuIntegrityChecker<K, V, N, P>
         where N : LfuNode<K, V>
         where P : struct, INodePolicy<K, V, N>
     {
-        private readonly ConcurrentLfu<K, V> cache;
+        private readonly ConcurrentLfuCore<K, V, N, P> cache;
 
         private readonly LfuNodeList<K, V> windowLru;
         private readonly LfuNodeList<K, V> probationLru;
@@ -334,7 +334,7 @@ internal class ConcurrentLfuIntegrityChecker<K, V, N, P>
         private static FieldInfo readBufferField = typeof(ConcurrentLfuCore<K, V, N, P>).GetField("readBuffer", BindingFlags.NonPublic | BindingFlags.Instance);
         private static FieldInfo writeBufferField = typeof(ConcurrentLfuCore<K, V, N, P>).GetField("writeBuffer", BindingFlags.NonPublic | BindingFlags.Instance);
 
-        public ConcurrentLfuIntegrityChecker(ConcurrentLfu<K, V> cache)
+        public ConcurrentLfuIntegrityChecker(ConcurrentLfuCore<K, V, N, P> cache)
         {
             this.cache = cache;
 
diff --git a/BitFaster.Caching/Lfu/ConcurrentLfu.cs b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
index efb5511a..d7f3e43c 100644
--- a/BitFaster.Caching/Lfu/ConcurrentLfu.cs
+++ b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
@@ -53,6 +53,8 @@ public ConcurrentLfu(int concurrencyLevel, int capacity, IScheduler scheduler, I
             this.core = new (concurrencyLevel, capacity, scheduler, comparer);
         }
 
+        internal ConcurrentLfuCore<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>> Core => core;
+
         ///<inheritdoc/>
         public int Count => core.Count;
 

From 325fb9edff64726254a43fe4ec4b8e590ffa5fce Mon Sep 17 00:00:00 2001
From: Alex Peck <alexpeck@microsoft.com>
Date: Sat, 2 Dec 2023 20:48:06 -0800
Subject: [PATCH 03/11] struct

---
 .../Lfu/ConcurrentLfuSoakTests.cs             |   1 -
 BitFaster.Caching/BitFaster.Caching.csproj    |   2 +-
 BitFaster.Caching/Lfu/ConcurrentLfu.cs        | 125 ++++++++----------
 3 files changed, 59 insertions(+), 69 deletions(-)

diff --git a/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuSoakTests.cs b/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuSoakTests.cs
index 5fceb2ec..00ab7247 100644
--- a/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuSoakTests.cs
+++ b/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuSoakTests.cs
@@ -307,7 +307,6 @@ private async Task RunIntegrityCheckAsync(ConcurrentLfu<int, string> lfu, int it
             RunIntegrityCheck(lfu, this.output);
         }
 
-
         private static void RunIntegrityCheck<K,V>(ConcurrentLfu<K,V> cache, ITestOutputHelper output)
         {
             new ConcurrentLfuIntegrityChecker<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>>(cache.Core).Validate(output);
diff --git a/BitFaster.Caching/BitFaster.Caching.csproj b/BitFaster.Caching/BitFaster.Caching.csproj
index 248e6559..9c14368a 100644
--- a/BitFaster.Caching/BitFaster.Caching.csproj
+++ b/BitFaster.Caching/BitFaster.Caching.csproj
@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <TargetFrameworks>netstandard2.0;netcoreapp3.1;net6.0</TargetFrameworks>
-    <LangVersion>9.0</LangVersion>
+    <LangVersion>11.0</LangVersion>
     <Authors>Alex Peck</Authors>
     <Company />
     <Product>BitFaster.Caching</Product>
diff --git a/BitFaster.Caching/Lfu/ConcurrentLfu.cs b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
index d7f3e43c..794f682a 100644
--- a/BitFaster.Caching/Lfu/ConcurrentLfu.cs
+++ b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
@@ -23,9 +23,12 @@ namespace BitFaster.Caching.Lfu
     /// <summary>
     /// Facade to hide generics.
     /// </summary>
+    [DebuggerTypeProxy(typeof(ConcurrentLfu<,>.LfuDebugView<>))]
+    [DebuggerDisplay("Count = {Count}/{Capacity}")]
     public sealed class ConcurrentLfu<K, V> : ICache<K, V>, IAsyncCache<K, V>, IBoundedPolicy
     {
-        private readonly ConcurrentLfuCore<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>> core;
+        // Note: for performance reasons this is a mutable struct, it cannot be readonly.
+        private ConcurrentLfuCore<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>> core;
 
         /// <summary>
         /// The default buffer size.
@@ -38,7 +41,7 @@ public sealed class ConcurrentLfu<K, V> : ICache<K, V>, IAsyncCache<K, V>, IBoun
         /// <param name="capacity">The capacity.</param>
         public ConcurrentLfu(int capacity)
         {
-            this.core = new (capacity);
+            this.core = new(Defaults.ConcurrencyLevel, capacity, new ThreadPoolScheduler(), EqualityComparer<K>.Default, () => this.DrainBuffers());
         }
 
         /// <summary>
@@ -50,11 +53,17 @@ public ConcurrentLfu(int capacity)
         /// <param name="comparer">The equality comparer.</param>
         public ConcurrentLfu(int concurrencyLevel, int capacity, IScheduler scheduler, IEqualityComparer<K> comparer)
         {
-            this.core = new (concurrencyLevel, capacity, scheduler, comparer);
+            this.core = new (concurrencyLevel, capacity, scheduler, comparer, () => this.DrainBuffers());
         }
 
         internal ConcurrentLfuCore<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>> Core => core;
 
+        // structs cannot declare self referencing lambda functions, therefore pass this in from the ctor
+        private void DrainBuffers()
+        {
+            this.core.DrainBuffers();
+        }
+
         ///<inheritdoc/>
         public int Count => core.Count;
 
@@ -183,6 +192,41 @@ public string FormatLfuString()
             return core.FormatLfuString();
         }
 #endif
+
+        [ExcludeFromCodeCoverage]
+        internal class LfuDebugView<N>
+             where N : LfuNode<K, V>
+        {
+            private readonly ConcurrentLfu<K, V> lfu;
+
+            public LfuDebugView(ConcurrentLfu<K, V> lfu)
+            {
+                this.lfu = lfu;
+            }
+
+            public string Maintenance => lfu.core.drainStatus.Format();
+
+            public ICacheMetrics Metrics => lfu.Metrics.Value;
+
+            public StripedMpscBuffer<N> ReadBuffer => this.lfu.core.readBuffer as StripedMpscBuffer<N>;
+
+            public MpscBoundedBuffer<N> WriteBuffer => this.lfu.core.writeBuffer as MpscBoundedBuffer<N>;
+
+            public KeyValuePair<K, V>[] Items
+            {
+                get
+                {
+                    var items = new KeyValuePair<K, V>[lfu.Count];
+
+                    int index = 0;
+                    foreach (var kvp in lfu)
+                    {
+                        items[index++] = kvp;
+                    }
+                    return items;
+                }
+            }
+        }
     }
 
     /// <summary>
@@ -205,23 +249,19 @@ public string FormatLfuString()
     /// </summary>
     /// Based on the Caffeine library by ben.manes@gmail.com (Ben Manes).
     /// https://github.com/ben-manes/caffeine
-    [DebuggerTypeProxy(typeof(ConcurrentLfuCore<,,,>.LfuDebugView))]
-    [DebuggerDisplay("Count = {Count}/{Capacity}")]
-    internal sealed class ConcurrentLfuCore<K, V, N, P> : ICache<K, V>, IAsyncCache<K, V>, IBoundedPolicy
+    
+    internal struct ConcurrentLfuCore<K, V, N, P> : ICache<K, V>, IAsyncCache<K, V>, IBoundedPolicy
         where N : LfuNode<K, V>
         where P : struct, INodePolicy<K, V, N>
     {
         private const int MaxWriteBufferRetries = 64;
 
-        /// <summary>
-        /// The default buffer size.
-        /// </summary>
-        public const int DefaultBufferSize = 128;
+        private const int DefaultBufferSize = 128;
 
         private readonly ConcurrentDictionary<K, N> dictionary;
 
-        private readonly StripedMpscBuffer<N> readBuffer;
-        private readonly MpscBoundedBuffer<N> writeBuffer;
+        internal readonly StripedMpscBuffer<N> readBuffer;
+        internal readonly MpscBoundedBuffer<N> writeBuffer;
 
         private readonly CacheMetrics metrics = new();
 
@@ -233,7 +273,7 @@ internal sealed class ConcurrentLfuCore<K, V, N, P> : ICache<K, V>, IAsyncCache<
 
         private readonly LfuCapacityPartition capacity;
 
-        private readonly DrainStatus drainStatus = new();
+        internal readonly DrainStatus drainStatus = new();
         private readonly object maintenanceLock = new();
 
         private readonly IScheduler scheduler;
@@ -241,23 +281,7 @@ internal sealed class ConcurrentLfuCore<K, V, N, P> : ICache<K, V>, IAsyncCache<
 
         private readonly N[] drainBuffer;
 
-        /// <summary>
-        /// Initializes a new instance of the ConcurrentLfu class with the specified capacity.
-        /// </summary>
-        /// <param name="capacity">The capacity.</param>
-        public ConcurrentLfuCore(int capacity)
-            : this(Defaults.ConcurrencyLevel, capacity, new ThreadPoolScheduler(), EqualityComparer<K>.Default)
-        {        
-        }
-
-        /// <summary>
-        /// Initializes a new instance of the ConcurrentLfu class with the specified concurrencyLevel, capacity, scheduler, equality comparer and buffer size.
-        /// </summary>
-        /// <param name="concurrencyLevel">The concurrency level.</param>
-        /// <param name="capacity">The capacity.</param>
-        /// <param name="scheduler">The scheduler.</param>
-        /// <param name="comparer">The equality comparer.</param>
-        public ConcurrentLfuCore(int concurrencyLevel, int capacity, IScheduler scheduler, IEqualityComparer<K> comparer)
+        public ConcurrentLfuCore(int concurrencyLevel, int capacity, IScheduler scheduler, IEqualityComparer<K> comparer, Action drainBuffers)
         {
             int dictionaryCapacity = ConcurrentDictionarySize.Estimate(capacity);
             this.dictionary = new (concurrencyLevel, dictionaryCapacity, comparer);
@@ -278,9 +302,10 @@ public ConcurrentLfuCore(int concurrencyLevel, int capacity, IScheduler schedule
             this.capacity = new LfuCapacityPartition(capacity);
 
             this.scheduler = scheduler;
-            this.drainBuffers = () => this.DrainBuffers();
 
             this.drainBuffer = new N[this.readBuffer.Capacity];
+
+            this.drainBuffers = drainBuffers;
         }
 
         // No lock count: https://arbel.net/2013/02/03/best-practices-for-using-concurrentdictionary/
@@ -713,7 +738,7 @@ private void TryScheduleDrain()
             }
         }
 
-        private void DrainBuffers()
+        internal void DrainBuffers()
         {
             bool done = false;
 
@@ -1026,7 +1051,7 @@ private void ReFitProtected()
         }
 
         [DebuggerDisplay("{Format(),nq}")]
-        private class DrainStatus
+        internal class DrainStatus
         {
             public const int Idle = 0;
             public const int Required = 1;
@@ -1138,40 +1163,6 @@ public string FormatLfuString()
             return sb.ToString();
         }
 #endif
-
-        [ExcludeFromCodeCoverage]
-        internal class LfuDebugView
-        {
-            private readonly ConcurrentLfuCore<K, V, N, P> lfu;
-
-            public LfuDebugView(ConcurrentLfuCore<K, V, N, P> lfu)
-            {
-                this.lfu = lfu;
-            }
-
-            public string Maintenance => lfu.drainStatus.Format();
-
-            public ICacheMetrics Metrics => lfu.metrics;
-
-            public StripedMpscBuffer<N> ReadBuffer => this.lfu.readBuffer;
-
-            public MpscBoundedBuffer<N> WriteBuffer => this.lfu.writeBuffer;
-
-            public KeyValuePair<K, V>[] Items
-            {
-                get
-                {
-                    var items = new KeyValuePair<K, V>[lfu.Count];
-
-                    int index = 0;
-                    foreach (var kvp in lfu)
-                    {
-                        items[index++] = kvp;
-                    }
-                    return items;
-                }
-            }
-        }
     }
 
     // Explicit layout cannot be a generic class member

From 3353e3347fed556caeac358ec8b0bb3de1755da0 Mon Sep 17 00:00:00 2001
From: Alex Peck <alexpeck@microsoft.com>
Date: Sat, 2 Dec 2023 21:04:04 -0800
Subject: [PATCH 04/11] fix docs

---
 BitFaster.Caching/Lfu/ConcurrentLfu.cs | 98 ++++++++------------------
 1 file changed, 29 insertions(+), 69 deletions(-)

diff --git a/BitFaster.Caching/Lfu/ConcurrentLfu.cs b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
index 794f682a..bd4a59e1 100644
--- a/BitFaster.Caching/Lfu/ConcurrentLfu.cs
+++ b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
@@ -21,8 +21,25 @@
 namespace BitFaster.Caching.Lfu
 {
     /// <summary>
-    /// Facade to hide generics.
+    /// An approximate LFU based on the W-TinyLfu eviction policy. W-TinyLfu tracks items using a window LRU list, and 
+    /// a main space LRU divided into protected and probation segments. Reads and writes to the cache are stored in buffers
+    /// and later applied to the policy LRU lists in batches under a lock. Each read and write is tracked using a compact 
+    /// popularity sketch to probalistically estimate item frequency. Items proceed through the LRU lists as follows:
+    /// <list type="number">
+    ///   <item><description>New items are added to the window LRU. When acessed window items move to the window MRU position.</description></item>
+    ///   <item><description>When the window is full, candidate items are moved to the probation segment in LRU order.</description></item>
+    ///   <item><description>When the main space is full, the access frequency of each window candidate is compared 
+    ///   to probation victims in LRU order. The item with the lowest frequency is evicted until the cache size is within bounds.</description></item>
+    ///   <item><description>When a probation item is accessed, it is moved to the protected segment. If the protected segment is full, 
+    ///   the LRU protected item is demoted to probation.</description></item>
+    ///   <item><description>When a protected item is accessed, it is moved to the protected MRU position.</description></item>
+    /// </list>
+    /// The size of the admission window and main space are adapted over time to iteratively improve hit rate using a 
+    /// hill climbing algorithm. A larger window favors workloads with high recency bias, whereas a larger main space
+    /// favors workloads with frequency bias.
     /// </summary>
+    /// Based on the Caffeine library by ben.manes@gmail.com (Ben Manes).
+    /// https://github.com/ben-manes/caffeine
     [DebuggerTypeProxy(typeof(ConcurrentLfu<,>.LfuDebugView<>))]
     [DebuggerDisplay("Count = {Count}/{Capacity}")]
     public sealed class ConcurrentLfu<K, V> : ICache<K, V>, IAsyncCache<K, V>, IBoundedPolicy
@@ -158,13 +175,22 @@ public bool TryRemove(K key)
             return core.TryRemove(key);
         }
 
-        ///<inheritdoc/>
+        /// <summary>
+        /// Attempts to remove the specified key value pair.
+        /// </summary>
+        /// <param name="item">The item to remove.</param>
+        /// <returns>true if the item was removed successfully; otherwise, false.</returns>
         public bool TryRemove(KeyValuePair<K, V> item)
         {
             return core.TryRemove(item);
         }
 
-        ///<inheritdoc/>
+        /// <summary>
+        /// Attempts to remove and return the value that has the specified key.
+        /// </summary>
+        /// <param name="key">The key of the element to remove.</param>
+        /// <param name="value">When this method returns, contains the object removed, or the default value of the value type if key does not exist.</param>
+        /// <returns>true if the object was removed successfully; otherwise, false.</returns>
         public bool TryRemove(K key, out V value)
         {
             return core.TryRemove(key, out value);
@@ -309,30 +335,20 @@ public ConcurrentLfuCore(int concurrencyLevel, int capacity, IScheduler schedule
         }
 
         // No lock count: https://arbel.net/2013/02/03/best-practices-for-using-concurrentdictionary/
-        ///<inheritdoc/>
         public int Count => this.dictionary.Skip(0).Count();
 
-        ///<inheritdoc/>
         public int Capacity => this.capacity.Capacity;
 
-        ///<inheritdoc/>
         public Optional<ICacheMetrics> Metrics => new(this.metrics);
 
-        ///<inheritdoc/>
         public Optional<ICacheEvents<K, V>> Events => Optional<ICacheEvents<K, V>>.None();
 
-        ///<inheritdoc/>
         public CachePolicy Policy => new(new Optional<IBoundedPolicy>(this), Optional<ITimePolicy>.None());
 
-        ///<inheritdoc/>
         public ICollection<K> Keys => this.dictionary.Keys;
 
-        /// <summary>
-        /// Gets the scheduler.
-        /// </summary>
         public IScheduler Scheduler => scheduler;
 
-        ///<inheritdoc/>
         public void AddOrUpdate(K key, V value)
         {
             while (true)
@@ -351,7 +367,6 @@ public void AddOrUpdate(K key, V value)
             }
         }
 
-        ///<inheritdoc/>
         public void Clear()
         {
             this.Trim(this.Count);
@@ -364,10 +379,6 @@ public void Clear()
             }
         }
 
-        /// <summary>
-        /// Trim the specified number of items from the cache.
-        /// </summary>
-        /// <param name="itemCount">The number of items to remove.</param>
         public void Trim(int itemCount)
         {
             itemCount = Math.Min(itemCount, this.Count);
@@ -409,7 +420,6 @@ private bool TryAdd(K key, V value)
             return false;
         }
 
-        ///<inheritdoc/>
         public V GetOrAdd(K key, Func<K, V> valueFactory)
         {
             while (true)
@@ -427,16 +437,6 @@ public V GetOrAdd(K key, Func<K, V> valueFactory)
             }
         }
 
-        /// <summary>
-        /// Adds a key/value pair to the cache if the key does not already exist. Returns the new value, or the 
-        /// existing value if the key already exists.
-        /// </summary>
-        /// <typeparam name="TArg">The type of an argument to pass into valueFactory.</typeparam>
-        /// <param name="key">The key of the element to add.</param>
-        /// <param name="valueFactory">The factory function used to generate a value for the key.</param>
-        /// <param name="factoryArgument">An argument value to pass into valueFactory.</param>
-        /// <returns>The value for the key. This will be either the existing value for the key if the key is already 
-        /// in the cache, or the new value if the key was not in the cache.</returns>
         public V GetOrAdd<TArg>(K key, Func<K, TArg, V> valueFactory, TArg factoryArgument)
         {
             while (true)
@@ -454,7 +454,6 @@ public V GetOrAdd<TArg>(K key, Func<K, TArg, V> valueFactory, TArg factoryArgume
             }
         }
 
-        ///<inheritdoc/>
         public async ValueTask<V> GetOrAddAsync(K key, Func<K, Task<V>> valueFactory)
         {
             while (true)
@@ -472,15 +471,6 @@ public async ValueTask<V> GetOrAddAsync(K key, Func<K, Task<V>> valueFactory)
             }
         }
 
-        /// <summary>
-        /// Adds a key/value pair to the cache if the key does not already exist. Returns the new value, or the 
-        /// existing value if the key already exists.
-        /// </summary>
-        /// <typeparam name="TArg">The type of an argument to pass into valueFactory.</typeparam>
-        /// <param name="key">The key of the element to add.</param>
-        /// <param name="valueFactory">The factory function used to asynchronously generate a value for the key.</param>
-        /// <param name="factoryArgument">An argument value to pass into valueFactory.</param>
-        /// <returns>A task that represents the asynchronous GetOrAdd operation.</returns>
         public async ValueTask<V> GetOrAddAsync<TArg>(K key, Func<K, TArg, Task<V>> valueFactory, TArg factoryArgument)
         {
             while (true)
@@ -498,7 +488,6 @@ public async ValueTask<V> GetOrAddAsync<TArg>(K key, Func<K, TArg, Task<V>> valu
             }
         }
 
-        ///<inheritdoc/>
         public bool TryGet(K key, out V value)
         {
             if (this.dictionary.TryGetValue(key, out var node))
@@ -519,11 +508,6 @@ public bool TryGet(K key, out V value)
             return false;
         }
 
-        /// <summary>
-        /// Attempts to remove the specified key value pair.
-        /// </summary>
-        /// <param name="item">The item to remove.</param>
-        /// <returns>true if the item was removed successfully; otherwise, false.</returns>
         public bool TryRemove(KeyValuePair<K, V> item)
         {
             if (this.dictionary.TryGetValue(item.Key, out var node))
@@ -549,12 +533,6 @@ public bool TryRemove(KeyValuePair<K, V> item)
             return false;
         }
 
-        /// <summary>
-        /// Attempts to remove and return the value that has the specified key.
-        /// </summary>
-        /// <param name="key">The key of the element to remove.</param>
-        /// <param name="value">When this method returns, contains the object removed, or the default value of the value type if key does not exist.</param>
-        /// <returns>true if the object was removed successfully; otherwise, false.</returns>
         public bool TryRemove(K key, out V value)
         {
             if (this.dictionary.TryRemove(key, out var node))
@@ -569,13 +547,11 @@ public bool TryRemove(K key, out V value)
             return false;
         }
 
-        ///<inheritdoc/>
         public bool TryRemove(K key)
         {
             return this.TryRemove(key, out var _);
         }
 
-        ///<inheritdoc/>
         public bool TryUpdate(K key, V value)
         {
             if (this.dictionary.TryGetValue(key, out var node))
@@ -592,27 +568,11 @@ public bool TryUpdate(K key, V value)
             return false;
         }
 
-        /// <summary>
-        /// Synchronously perform all pending policy maintenance. Drain the read and write buffers then
-        /// use the eviction policy to preserve bounded size and remove expired items.
-        /// </summary>
-        /// <remarks>
-        /// Note: maintenance is automatically performed asynchronously immediately following a read or write.
-        /// It is not necessary to call this method, <see cref="DoMaintenance"/> is provided purely to enable tests to reach a consistent state.
-        /// </remarks>
         public void DoMaintenance()
         {
             DrainBuffers();
         }
 
-        /// <summary>Returns an enumerator that iterates through the cache.</summary>
-        /// <returns>An enumerator for the cache.</returns>
-        /// <remarks>
-        /// The enumerator returned from the cache is safe to use concurrently with
-        /// reads and writes, however it does not represent a moment-in-time snapshot.  
-        /// The contents exposed through the enumerator may contain modifications
-        /// made after <see cref="GetEnumerator"/> was called.
-        /// </remarks>
         public IEnumerator<KeyValuePair<K, V>> GetEnumerator()
         {
             foreach (var kvp in this.dictionary)

From 77b8761e7f3a4937e28b01236b4be32740dc4558 Mon Sep 17 00:00:00 2001
From: Alex Peck <alexpeck@microsoft.com>
Date: Sat, 2 Dec 2023 21:05:40 -0800
Subject: [PATCH 05/11] lang10

---
 BitFaster.Caching/BitFaster.Caching.csproj | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/BitFaster.Caching/BitFaster.Caching.csproj b/BitFaster.Caching/BitFaster.Caching.csproj
index 9c14368a..60aa9ccc 100644
--- a/BitFaster.Caching/BitFaster.Caching.csproj
+++ b/BitFaster.Caching/BitFaster.Caching.csproj
@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <TargetFrameworks>netstandard2.0;netcoreapp3.1;net6.0</TargetFrameworks>
-    <LangVersion>11.0</LangVersion>
+    <LangVersion>10.0</LangVersion>
     <Authors>Alex Peck</Authors>
     <Company />
     <Product>BitFaster.Caching</Product>

From b0e90cb56c2da77342eb20029c02d9724482a92e Mon Sep 17 00:00:00 2001
From: Alex Peck <alexpeck@microsoft.com>
Date: Sat, 2 Dec 2023 21:28:23 -0800
Subject: [PATCH 06/11] enum

---
 BitFaster.Caching/Lfu/ConcurrentLfu.cs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/BitFaster.Caching/Lfu/ConcurrentLfu.cs b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
index bd4a59e1..eb95fd1b 100644
--- a/BitFaster.Caching/Lfu/ConcurrentLfu.cs
+++ b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
@@ -205,7 +205,7 @@ public bool TryUpdate(K key, V value)
         ///<inheritdoc/>
         IEnumerator IEnumerable.GetEnumerator()
         {
-            return core.GetEnumerator();
+            return ((ConcurrentLfuCore<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>>)core).GetEnumerator();
         }
 
 #if DEBUG

From e36165069c3602234c1c79d916a945e63dd390d8 Mon Sep 17 00:00:00 2001
From: Alex Peck <alexpeck@microsoft.com>
Date: Sat, 2 Dec 2023 21:36:26 -0800
Subject: [PATCH 07/11] capacity

---
 .../Lfu/ConcurrentLfuTests.cs                 | 24 +++++++++++++++++++
 BitFaster.Caching/Lfu/ConcurrentLfu.cs        |  3 +++
 2 files changed, 27 insertions(+)

diff --git a/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs b/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs
index 791c534a..e60b72a3 100644
--- a/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs
+++ b/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs
@@ -26,6 +26,30 @@ public ConcurrentLfuTests(ITestOutputHelper output)
             this.output = output;
         }
 
+        [Fact]
+        public void WhenCapacityIsLessThan3CtorThrows()
+        {
+            Action constructor = () => { var x = new ConcurrentLfu<int, string>(2); };
+
+            constructor.Should().Throw<ArgumentOutOfRangeException>();
+        }
+
+        [Fact]
+        public void WhenCapacityIsValidCacheIsCreated()
+        {
+            var x = new ConcurrentLfu<int, string>(3);
+
+            x.Capacity.Should().Be(3);
+        }
+
+        [Fact]
+        public void WhenConcurrencyIsLessThan1CtorThrows()
+        {
+            Action constructor = () => { var x = new ConcurrentLfu<int, string>(0, 20, new ForegroundScheduler(), EqualityComparer<int>.Default); };
+
+            constructor.Should().Throw<ArgumentOutOfRangeException>();
+        }
+
         [Fact]
         public void DefaultSchedulerIsThreadPool()
         {
diff --git a/BitFaster.Caching/Lfu/ConcurrentLfu.cs b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
index eb95fd1b..654463a0 100644
--- a/BitFaster.Caching/Lfu/ConcurrentLfu.cs
+++ b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
@@ -309,6 +309,9 @@ internal struct ConcurrentLfuCore<K, V, N, P> : ICache<K, V>, IAsyncCache<K, V>,
 
         public ConcurrentLfuCore(int concurrencyLevel, int capacity, IScheduler scheduler, IEqualityComparer<K> comparer, Action drainBuffers)
         {
+            if (capacity < 3)
+                Throw.ArgOutOfRange(nameof(capacity));
+
             int dictionaryCapacity = ConcurrentDictionarySize.Estimate(capacity);
             this.dictionary = new (concurrencyLevel, dictionaryCapacity, comparer);
 

From 9c5d849548f21e58f9511bc8aa5e7a16a25d5118 Mon Sep 17 00:00:00 2001
From: Alex Peck <alexpeck@microsoft.com>
Date: Sat, 2 Dec 2023 22:34:09 -0800
Subject: [PATCH 08/11] remove metrics/events from core

---
 .../Lfu/ConcurrentLfuTests.cs                 |  8 +++--
 BitFaster.Caching/Lfu/ConcurrentLfu.cs        | 36 +++++++------------
 2 files changed, 18 insertions(+), 26 deletions(-)

diff --git a/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs b/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs
index e60b72a3..e3ca7a46 100644
--- a/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs
+++ b/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs
@@ -1,10 +1,8 @@
 using System;
 using System.Collections;
 using System.Collections.Generic;
-using System.Diagnostics;
 using System.Linq;
 using System.Threading.Tasks;
-using BitFaster.Caching.Buffers;
 using BitFaster.Caching.Lfu;
 using BitFaster.Caching.Scheduler;
 using BitFaster.Caching.UnitTests.Lru;
@@ -572,7 +570,11 @@ public void WhenItemsAddedGenericEnumerateContainsKvps()
             cache.GetOrAdd(1, k => k + 1);
             cache.GetOrAdd(2, k => k + 1);
 
-            cache.Should().BeEquivalentTo(new[] { new KeyValuePair<int, int>(1, 2), new KeyValuePair<int, int>(2, 3) });
+            var enumerator = cache.GetEnumerator();
+            enumerator.MoveNext().Should().BeTrue();
+            enumerator.Current.Should().Be(new KeyValuePair<int, int>(1, 2));
+            enumerator.MoveNext().Should().BeTrue();
+            enumerator.Current.Should().Be(new KeyValuePair<int, int>(2, 3));
         }
 
         [Fact]
diff --git a/BitFaster.Caching/Lfu/ConcurrentLfu.cs b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
index 654463a0..b9a7f052 100644
--- a/BitFaster.Caching/Lfu/ConcurrentLfu.cs
+++ b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
@@ -85,13 +85,13 @@ private void DrainBuffers()
         public int Count => core.Count;
 
         ///<inheritdoc/>
-        public Optional<ICacheMetrics> Metrics => core.Metrics;
+        public Optional<ICacheMetrics> Metrics => new(this.core.metrics);
 
         ///<inheritdoc/>
-        public Optional<ICacheEvents<K, V>> Events => core.Events;
+        public Optional<ICacheEvents<K, V>> Events => Optional<ICacheEvents<K, V>>.None();
 
         ///<inheritdoc/>
-        public CachePolicy Policy => core.Policy;
+        public CachePolicy Policy => new(new Optional<IBoundedPolicy>(this), Optional<ITimePolicy>.None());
 
         ///<inheritdoc/>
         public ICollection<K> Keys => core.Keys;
@@ -127,12 +127,6 @@ public void Clear()
             core.Clear();
         }
 
-        ///<inheritdoc/>
-        public IEnumerator<KeyValuePair<K, V>> GetEnumerator()
-        {
-            return core.GetEnumerator();
-        }
-
         ///<inheritdoc/>
         public V GetOrAdd(K key, Func<K, V> valueFactory)
         {
@@ -202,10 +196,17 @@ public bool TryUpdate(K key, V value)
             return core.TryUpdate(key, value);
         }
 
+        ///<inheritdoc/>
+        public IEnumerator<KeyValuePair<K, V>> GetEnumerator()
+        {
+            return core.GetEnumerator();
+        }
+
         ///<inheritdoc/>
         IEnumerator IEnumerable.GetEnumerator()
         {
-            return ((ConcurrentLfuCore<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>>)core).GetEnumerator();
+            return core.GetEnumerator();
+            //return ((ConcurrentLfuCore<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>>)core).GetEnumerator();
         }
 
 #if DEBUG
@@ -276,7 +277,7 @@ public KeyValuePair<K, V>[] Items
     /// Based on the Caffeine library by ben.manes@gmail.com (Ben Manes).
     /// https://github.com/ben-manes/caffeine
     
-    internal struct ConcurrentLfuCore<K, V, N, P> : ICache<K, V>, IAsyncCache<K, V>, IBoundedPolicy
+    internal struct ConcurrentLfuCore<K, V, N, P> : IBoundedPolicy
         where N : LfuNode<K, V>
         where P : struct, INodePolicy<K, V, N>
     {
@@ -289,7 +290,7 @@ internal struct ConcurrentLfuCore<K, V, N, P> : ICache<K, V>, IAsyncCache<K, V>,
         internal readonly StripedMpscBuffer<N> readBuffer;
         internal readonly MpscBoundedBuffer<N> writeBuffer;
 
-        private readonly CacheMetrics metrics = new();
+        internal readonly CacheMetrics metrics = new();
 
         private readonly CmSketch<K> cmSketch;
 
@@ -342,12 +343,6 @@ public ConcurrentLfuCore(int concurrencyLevel, int capacity, IScheduler schedule
 
         public int Capacity => this.capacity.Capacity;
 
-        public Optional<ICacheMetrics> Metrics => new(this.metrics);
-
-        public Optional<ICacheEvents<K, V>> Events => Optional<ICacheEvents<K, V>>.None();
-
-        public CachePolicy Policy => new(new Optional<IBoundedPolicy>(this), Optional<ITimePolicy>.None());
-
         public ICollection<K> Keys => this.dictionary.Keys;
 
         public IScheduler Scheduler => scheduler;
@@ -662,11 +657,6 @@ private void ScheduleAfterWrite()
             }
         }
 
-        IEnumerator IEnumerable.GetEnumerator()
-        {
-            return ((ConcurrentLfuCore<K, V, N, P>)this).GetEnumerator();
-        }
-
         private void TryScheduleDrain()
         {
             if (this.drainStatus.VolatileRead() >= DrainStatus.ProcessingToIdle)

From 9215f83bdcea29242dca003b0725b6e02f4c0d3f Mon Sep 17 00:00:00 2001
From: Alex Peck <alexpeck@microsoft.com>
Date: Sat, 2 Dec 2023 22:48:37 -0800
Subject: [PATCH 09/11] Revert "remove metrics/events from core"

This reverts commit 9c5d849548f21e58f9511bc8aa5e7a16a25d5118.
---
 .../Lfu/ConcurrentLfuTests.cs                 |  8 ++---
 BitFaster.Caching/Lfu/ConcurrentLfu.cs        | 36 ++++++++++++-------
 2 files changed, 26 insertions(+), 18 deletions(-)

diff --git a/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs b/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs
index e3ca7a46..e60b72a3 100644
--- a/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs
+++ b/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs
@@ -1,8 +1,10 @@
 using System;
 using System.Collections;
 using System.Collections.Generic;
+using System.Diagnostics;
 using System.Linq;
 using System.Threading.Tasks;
+using BitFaster.Caching.Buffers;
 using BitFaster.Caching.Lfu;
 using BitFaster.Caching.Scheduler;
 using BitFaster.Caching.UnitTests.Lru;
@@ -570,11 +572,7 @@ public void WhenItemsAddedGenericEnumerateContainsKvps()
             cache.GetOrAdd(1, k => k + 1);
             cache.GetOrAdd(2, k => k + 1);
 
-            var enumerator = cache.GetEnumerator();
-            enumerator.MoveNext().Should().BeTrue();
-            enumerator.Current.Should().Be(new KeyValuePair<int, int>(1, 2));
-            enumerator.MoveNext().Should().BeTrue();
-            enumerator.Current.Should().Be(new KeyValuePair<int, int>(2, 3));
+            cache.Should().BeEquivalentTo(new[] { new KeyValuePair<int, int>(1, 2), new KeyValuePair<int, int>(2, 3) });
         }
 
         [Fact]
diff --git a/BitFaster.Caching/Lfu/ConcurrentLfu.cs b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
index b9a7f052..654463a0 100644
--- a/BitFaster.Caching/Lfu/ConcurrentLfu.cs
+++ b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
@@ -85,13 +85,13 @@ private void DrainBuffers()
         public int Count => core.Count;
 
         ///<inheritdoc/>
-        public Optional<ICacheMetrics> Metrics => new(this.core.metrics);
+        public Optional<ICacheMetrics> Metrics => core.Metrics;
 
         ///<inheritdoc/>
-        public Optional<ICacheEvents<K, V>> Events => Optional<ICacheEvents<K, V>>.None();
+        public Optional<ICacheEvents<K, V>> Events => core.Events;
 
         ///<inheritdoc/>
-        public CachePolicy Policy => new(new Optional<IBoundedPolicy>(this), Optional<ITimePolicy>.None());
+        public CachePolicy Policy => core.Policy;
 
         ///<inheritdoc/>
         public ICollection<K> Keys => core.Keys;
@@ -127,6 +127,12 @@ public void Clear()
             core.Clear();
         }
 
+        ///<inheritdoc/>
+        public IEnumerator<KeyValuePair<K, V>> GetEnumerator()
+        {
+            return core.GetEnumerator();
+        }
+
         ///<inheritdoc/>
         public V GetOrAdd(K key, Func<K, V> valueFactory)
         {
@@ -196,17 +202,10 @@ public bool TryUpdate(K key, V value)
             return core.TryUpdate(key, value);
         }
 
-        ///<inheritdoc/>
-        public IEnumerator<KeyValuePair<K, V>> GetEnumerator()
-        {
-            return core.GetEnumerator();
-        }
-
         ///<inheritdoc/>
         IEnumerator IEnumerable.GetEnumerator()
         {
-            return core.GetEnumerator();
-            //return ((ConcurrentLfuCore<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>>)core).GetEnumerator();
+            return ((ConcurrentLfuCore<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>>)core).GetEnumerator();
         }
 
 #if DEBUG
@@ -277,7 +276,7 @@ public KeyValuePair<K, V>[] Items
     /// Based on the Caffeine library by ben.manes@gmail.com (Ben Manes).
     /// https://github.com/ben-manes/caffeine
     
-    internal struct ConcurrentLfuCore<K, V, N, P> : IBoundedPolicy
+    internal struct ConcurrentLfuCore<K, V, N, P> : ICache<K, V>, IAsyncCache<K, V>, IBoundedPolicy
         where N : LfuNode<K, V>
         where P : struct, INodePolicy<K, V, N>
     {
@@ -290,7 +289,7 @@ internal struct ConcurrentLfuCore<K, V, N, P> : IBoundedPolicy
         internal readonly StripedMpscBuffer<N> readBuffer;
         internal readonly MpscBoundedBuffer<N> writeBuffer;
 
-        internal readonly CacheMetrics metrics = new();
+        private readonly CacheMetrics metrics = new();
 
         private readonly CmSketch<K> cmSketch;
 
@@ -343,6 +342,12 @@ public ConcurrentLfuCore(int concurrencyLevel, int capacity, IScheduler schedule
 
         public int Capacity => this.capacity.Capacity;
 
+        public Optional<ICacheMetrics> Metrics => new(this.metrics);
+
+        public Optional<ICacheEvents<K, V>> Events => Optional<ICacheEvents<K, V>>.None();
+
+        public CachePolicy Policy => new(new Optional<IBoundedPolicy>(this), Optional<ITimePolicy>.None());
+
         public ICollection<K> Keys => this.dictionary.Keys;
 
         public IScheduler Scheduler => scheduler;
@@ -657,6 +662,11 @@ private void ScheduleAfterWrite()
             }
         }
 
+        IEnumerator IEnumerable.GetEnumerator()
+        {
+            return ((ConcurrentLfuCore<K, V, N, P>)this).GetEnumerator();
+        }
+
         private void TryScheduleDrain()
         {
             if (this.drainStatus.VolatileRead() >= DrainStatus.ProcessingToIdle)

From 3e3dc31daa001c4749d92e8c1f454cfc0e3d157c Mon Sep 17 00:00:00 2001
From: Alex Peck <alexpeck@microsoft.com>
Date: Sat, 2 Dec 2023 23:05:00 -0800
Subject: [PATCH 10/11] rem interfaces

---
 .../Lfu/ConcurrentLfuTests.cs                 |  6 +++++-
 BitFaster.Caching/Lfu/ConcurrentLfu.cs        | 21 +++++++------------
 2 files changed, 13 insertions(+), 14 deletions(-)

diff --git a/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs b/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs
index e60b72a3..b806d867 100644
--- a/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs
+++ b/BitFaster.Caching.UnitTests/Lfu/ConcurrentLfuTests.cs
@@ -572,7 +572,11 @@ public void WhenItemsAddedGenericEnumerateContainsKvps()
             cache.GetOrAdd(1, k => k + 1);
             cache.GetOrAdd(2, k => k + 1);
 
-            cache.Should().BeEquivalentTo(new[] { new KeyValuePair<int, int>(1, 2), new KeyValuePair<int, int>(2, 3) });
+            var enumerator = cache.GetEnumerator();
+            enumerator.MoveNext().Should().BeTrue();
+            enumerator.Current.Should().Be(new KeyValuePair<int, int>(1, 2));
+            enumerator.MoveNext().Should().BeTrue();
+            enumerator.Current.Should().Be(new KeyValuePair<int, int>(2, 3));
         }
 
         [Fact]
diff --git a/BitFaster.Caching/Lfu/ConcurrentLfu.cs b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
index 654463a0..9065fa58 100644
--- a/BitFaster.Caching/Lfu/ConcurrentLfu.cs
+++ b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
@@ -127,12 +127,6 @@ public void Clear()
             core.Clear();
         }
 
-        ///<inheritdoc/>
-        public IEnumerator<KeyValuePair<K, V>> GetEnumerator()
-        {
-            return core.GetEnumerator();
-        }
-
         ///<inheritdoc/>
         public V GetOrAdd(K key, Func<K, V> valueFactory)
         {
@@ -202,10 +196,16 @@ public bool TryUpdate(K key, V value)
             return core.TryUpdate(key, value);
         }
 
+        ///<inheritdoc/>
+        public IEnumerator<KeyValuePair<K, V>> GetEnumerator()
+        {
+            return core.GetEnumerator();
+        }
+
         ///<inheritdoc/>
         IEnumerator IEnumerable.GetEnumerator()
         {
-            return ((ConcurrentLfuCore<K, V, AccessOrderNode<K, V>, AccessOrderPolicy<K, V>>)core).GetEnumerator();
+            return core.GetEnumerator();
         }
 
 #if DEBUG
@@ -276,7 +276,7 @@ public KeyValuePair<K, V>[] Items
     /// Based on the Caffeine library by ben.manes@gmail.com (Ben Manes).
     /// https://github.com/ben-manes/caffeine
     
-    internal struct ConcurrentLfuCore<K, V, N, P> : ICache<K, V>, IAsyncCache<K, V>, IBoundedPolicy
+    internal struct ConcurrentLfuCore<K, V, N, P> : IBoundedPolicy
         where N : LfuNode<K, V>
         where P : struct, INodePolicy<K, V, N>
     {
@@ -662,11 +662,6 @@ private void ScheduleAfterWrite()
             }
         }
 
-        IEnumerator IEnumerable.GetEnumerator()
-        {
-            return ((ConcurrentLfuCore<K, V, N, P>)this).GetEnumerator();
-        }
-
         private void TryScheduleDrain()
         {
             if (this.drainStatus.VolatileRead() >= DrainStatus.ProcessingToIdle)

From cb8ce8d1dfc8f57f2aa03f676c3baedfa7a18f40 Mon Sep 17 00:00:00 2001
From: Alex Peck <alexpeck@microsoft.com>
Date: Sat, 2 Dec 2023 23:33:16 -0800
Subject: [PATCH 11/11] default switch

---
 BitFaster.Caching/Lfu/ConcurrentLfu.cs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/BitFaster.Caching/Lfu/ConcurrentLfu.cs b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
index 9065fa58..0faf7351 100644
--- a/BitFaster.Caching/Lfu/ConcurrentLfu.cs
+++ b/BitFaster.Caching/Lfu/ConcurrentLfu.cs
@@ -1026,8 +1026,8 @@ public bool ShouldDrain(bool delayable)
                 {
                     Idle => !delayable,
                     Required => true,
-                    ProcessingToIdle or ProcessingToRequired => false,
-                    _ => false,// not reachable
+                    // ProcessingToIdle or ProcessingToRequired => false, undefined not reachable
+                    _ => false,
                 };
             }