Implement GetOrAdd (#62)

* getoradd

* basic unit tests

* lru order tests

* use add instead of new

* test classic dispose on addorupdate

Author: bitfaster

BitFaster.Caching.UnitTests/Lru/ClassicLruTests.cs

@@ -276,5 +276,56 @@ public void WhenKeyDoesNotExistTryUpdateReturnsFalse()
 
             lru.TryUpdate(2, "3").Should().BeFalse();
         }
+
+        [Fact]
+        public void WhenKeyDoesNotExistAddOrUpdateAddsNewItem()
+        {
+            lru.AddOrUpdate(1, "1");
+
+            lru.TryGet(1, out var value).Should().BeTrue();
+            value.Should().Be("1");
+        }
+
+        [Fact]
+        public void WhenKeyExistsAddOrUpdatUpdatesExistingItem()
+        {
+            lru.AddOrUpdate(1, "1");
+            lru.AddOrUpdate(1, "2");
+
+            lru.TryGet(1, out var value).Should().BeTrue();
+            value.Should().Be("2");
+        }
+
+        [Fact]
+        public void WhenKeyDoesNotExistAddOrUpdateMaintainsLruOrder()
+        {
+            lru.AddOrUpdate(1, "1");
+            lru.AddOrUpdate(2, "2");
+            lru.AddOrUpdate(3, "3");
+            lru.AddOrUpdate(4, "4");
+
+            // verify first item added is removed
+            lru.Count.Should().Be(3);
+            lru.TryGet(1, out var value).Should().BeFalse();
+        }
+
+        [Fact]
+        public void WhenAddOrUpdateExpiresItemsTheyAreDisposed()
+        {
+            var lruOfDisposable = new ClassicLru<int, DisposableItem>(1, 3, EqualityComparer<int>.Default);
+
+            var items = Enumerable.Range(1, 4).Select(i => new DisposableItem()).ToList();
+
+            for (int i = 0; i < 4; i++)
+            {
+                lruOfDisposable.AddOrUpdate(i, items[i]);
+            }
+
+            // first item is evicted and disposed
+            items[0].IsDisposed.Should().BeTrue();
+
+            // all other items are not disposed
+            items.Skip(1).All(i => i.IsDisposed == false).Should().BeTrue();
+        }
     }
 }

BitFaster.Caching.UnitTests/Lru/ConcurrentLruTests.cs

@@ -392,5 +392,36 @@ public void WhenKeyDoesNotExistTryUpdateReturnsFalse()
 
             lru.TryUpdate(2, "3").Should().BeFalse();
         }
+
+        [Fact]
+        public void WhenKeyDoesNotExistAddOrUpdateAddsNewItem()
+        {
+            lru.AddOrUpdate(1, "1");
+
+            lru.TryGet(1, out var value).Should().BeTrue();
+            value.Should().Be("1");
+        }
+
+        [Fact]
+        public void WhenKeyExistsAddOrUpdatUpdatesExistingItem()
+        {
+            lru.AddOrUpdate(1, "1");
+            lru.AddOrUpdate(1, "2");
+
+            lru.TryGet(1, out var value).Should().BeTrue();
+            value.Should().Be("2");
+        }
+
+        [Fact]
+        public void WhenKeyDoesNotExistAddOrUpdateMaintainsLruOrder()
+        {
+            lru.AddOrUpdate(1, "1");
+            lru.AddOrUpdate(2, "2");
+            lru.AddOrUpdate(3, "3");
+            lru.AddOrUpdate(4, "4");
+
+            lru.HotCount.Should().Be(3);
+            lru.ColdCount.Should().Be(1); // items must have been enqueued and cycled for one of them to reach the cold queue
+        }
     }
 }

BitFaster.Caching/ICache.cs

@@ -54,5 +54,13 @@ public interface ICache<K, V>
         /// <param name="value">The new value.</param>
         /// <returns>true if the object was updated successfully; otherwise, false.</returns>
         bool TryUpdate(K key, V value);
+
+        /// <summary>
+        /// Adds a key/value pair to the cache if the key does not already exist, or updates a key/value pair if the 
+        /// key already exists.
+        /// </summary>
+        /// <param name="key">The key of the element to update.</param>
+        /// <param name="value">The new value.</param>
+        void AddOrUpdate(K key, V value);
     }
 }

BitFaster.Caching/Lru/ClassicLru.cs

@@ -206,6 +206,58 @@ public bool TryUpdate(K key, V value)
             return false;
         }
 
+        ///<inheritdoc/>
+        ///<remarks>Note: Updates to existing items do not affect LRU order. Added items are at the top of the LRU.</remarks>
+        public void AddOrUpdate(K key, V value)
+        { 
+            // first, try to update
+            if (this.dictionary.TryGetValue(key, out var existingNode))
+            {
+                existingNode.Value.Value = value;
+                return;
+            }
+
+            // then try add
+            var newNode = new LinkedListNode<LruItem>(new LruItem(key, value));
+
+            if (this.dictionary.TryAdd(key, newNode))
+            {
+                LinkedListNode<LruItem> first = null;
+
+                lock (this.linkedList)
+                {
+                    if (linkedList.Count >= capacity)
+                    {
+                        first = linkedList.First;
+                        linkedList.RemoveFirst();
+                    }
+
+                    linkedList.AddLast(newNode);
+                }
+
+                // Remove from the dictionary outside the lock. This means that the dictionary at this moment
+                // contains an item that is not in the linked list. If another thread fetches this item, 
+                // LockAndMoveToEnd will ignore it, since it is detached. This means we potentially 'lose' an 
+                // item just as it was about to move to the back of the LRU list and be preserved. The next request
+                // for the same key will be a miss. Dictionary and list are eventually consistent.
+                // However, all operations inside the lock are extremely fast, so contention is minimized.
+                if (first != null)
+                {
+                    dictionary.TryRemove(first.Value.Key, out var removed);
+
+                    if (removed.Value.Value is IDisposable d)
+                    {
+                        d.Dispose();
+                    }
+                }
+
+                return;
+            }
+
+            // if both update and add failed there was a race, try again
+            AddOrUpdate(key, value);
+        }
+
         // Thead A reads x from the dictionary. Thread B adds a new item. Thread A moves x to the end. Thread B now removes the new first Node (removal is atomic on both data structures).
         private void LockAndMoveToEnd(LinkedListNode<LruItem> node)
         {

BitFaster.Caching/Lru/TemplateConcurrentLru.cs

@@ -242,6 +242,38 @@ public bool TryUpdate(K key, V value)
             return false;
         }
 
+        ///<inheritdoc/>
+        ///<remarks>Note: Updates to existing items do not affect LRU order. Added items are at the top of the LRU.</remarks>
+        public void AddOrUpdate(K key, V value)
+        { 
+            // first, try to update
+            if (this.dictionary.TryGetValue(key, out var existing))
+            {
+                lock (existing)
+                {
+                    if (!existing.WasRemoved)
+                    {
+                        existing.Value = value;
+                        return;
+                    }
+                }
+            }
+
+            // then try add
+            var newItem = this.policy.CreateItem(key, value);
+
+            if (this.dictionary.TryAdd(key, newItem))
+            {
+                this.hotQueue.Enqueue(newItem);
+                Interlocked.Increment(ref hotCount);
+                Cycle();
+                return;
+            }
+
+            // if both update and add failed there was a race, try again
+            AddOrUpdate(key, value);
+        }
+
         private void Cycle()
         {
             // There will be races when queue count == queue capacity. Two threads may each dequeue items.