docs (#249)

* docs

* hc

Author: bitfaster

BitFaster.Caching/Lfu/CmSketch.cs

@@ -10,7 +10,7 @@ namespace BitFaster.Caching.Lfu
     /// </summary>
     /// <remarks>
     /// This is a direct C# translation of FrequencySketch in the Caffeine library by [email protected] (Ben Manes).
-    /// http://www.apache.org/licenses/LICENSE-2.0
+    /// https://github.com/ben-manes/caffeine
     /// </remarks>
     public sealed class CmSketch<T>
     {

BitFaster.Caching/Lfu/ConcurrentLfu.cs

@@ -20,11 +20,26 @@
 namespace BitFaster.Caching.Lfu
 {
     /// <summary>
-    /// An LFU cache with a W-TinyLfu eviction policy.
+    /// 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>
     /// <remarks>
-    /// Based on Caffeine written by Ben Manes.
-    /// https://www.apache.org/licenses/LICENSE-2.0
+    /// Based on the Caffeine library by [email protected] (Ben Manes).
+    /// https://github.com/ben-manes/caffeine
     /// </remarks>
     [DebuggerTypeProxy(typeof(ConcurrentLfu<,>.LfuDebugView))]
     [DebuggerDisplay("Count = {Count}/{Capacity}")]

BitFaster.Caching/Lru/ConcurrentLruCore.cs

@@ -11,22 +11,25 @@
 namespace BitFaster.Caching.Lru
 {
     /// <summary>
-    /// Pseudo LRU implementation where LRU list is composed of 3 segments: hot, warm and cold. Cost of maintaining
-    /// segments is amortized across requests. Items are only cycled when capacity is exceeded. Pure read does
-    /// not cycle items if all segments are within capacity constraints.
-    /// There are no global locks. On cache miss, a new item is added. Tail items in each segment are dequeued,
-    /// examined, and are either enqueued or discarded.
-    /// This scheme of hot, warm and cold is based on the implementation used in MemCached described online here:
-    /// https://memcached.org/blog/modern-lru/
+    /// A pseudo LRU based on the TU-Q eviction policy. The LRU list is composed of 3 segments: hot, warm and cold. 
+    /// Cost of maintaining segments is amortized across requests. Items are only cycled when capacity is exceeded. 
+    /// Pure read does not cycle items if all segments are within capacity constraints. There are no global locks. 
+    /// On cache miss, a new item is added. Tail items in each segment are dequeued, examined, and are either enqueued 
+    /// or discarded.
+    /// The TU-Q scheme of hot, warm and cold is similar to that used in MemCached (https://memcached.org/blog/modern-lru/)
+    /// and OpenBSD (https://flak.tedunangst.com/post/2Q-buffer-cache-algorithm), but does not use a background thread
+    /// to maintain the internal queues.
     /// </summary>
     /// <remarks>
     /// Each segment has a capacity. When segment capacity is exceeded, items are moved as follows:
-    /// 1. New items are added to hot, WasAccessed = false
-    /// 2. When items are accessed, update WasAccessed = true
-    /// 3. When items are moved WasAccessed is set to false.
-    /// 4. When hot is full, hot tail is moved to either Warm or Cold depending on WasAccessed. 
-    /// 5. When warm is full, warm tail is moved to warm head or cold depending on WasAccessed.
-    /// 6. When cold is full, cold tail is moved to warm head or removed from dictionary on depending on WasAccessed.
+    /// <list type="number">
+    ///   <item><description>New items are added to hot, WasAccessed = false.</description></item>
+    ///   <item><description>When items are accessed, update WasAccessed = true.</description></item>
+    ///   <item><description>When items are moved WasAccessed is set to false.</description></item>
+    ///   <item><description>When hot is full, hot tail is moved to either Warm or Cold depending on WasAccessed.</description></item>
+    ///   <item><description>When warm is full, warm tail is moved to warm head or cold depending on WasAccessed.</description></item>
+    ///   <item><description>When cold is full, cold tail is moved to warm head or removed from dictionary on depending on WasAccessed.</description></item>
+    ///</list>
     /// </remarks>
     public class ConcurrentLruCore<K, V, I, P, T> : ICache<K, V>, IAsyncCache<K, V>, IEnumerable<KeyValuePair<K, V>>
         where I : LruItem<K, V>