Implement minimal implementation of HybridCache (#55147)

initial implementation of `HybridCache`

Author: mgravell

AspNetCore.sln

@@ -1796,6 +1796,9 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Extensions.Cachin
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Extensions.Caching.Hybrid.Tests", "src\Caching\Hybrid\test\Microsoft.Extensions.Caching.Hybrid.Tests.csproj", "{CF63C942-895A-4F6B-888A-7653D7C4991A}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "MicroBenchmarks", "MicroBenchmarks", "{6469F11E-8CEE-4292-820B-324DFFC88EBC}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Extensions.Caching.MicroBenchmarks", "src\Caching\perf\MicroBenchmarks\Microsoft.Extensions.Caching.MicroBenchmarks\Microsoft.Extensions.Caching.MicroBenchmarks.csproj", "{8D2CC6ED-5105-4F52-8757-C21F4DE78589}"
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "perf", "perf", "{9DC6B242-457B-4767-A84B-C3D23B76C642}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microsoft.AspNetCore.OpenApi.Microbenchmarks", "src\OpenApi\perf\Microbenchmarks\Microsoft.AspNetCore.OpenApi.Microbenchmarks.csproj", "{D53F0EF7-0CDC-49B4-AA2D-229901B0A734}"
@@ -10849,6 +10852,22 @@ Global
 		{CF63C942-895A-4F6B-888A-7653D7C4991A}.Release|x64.Build.0 = Release|Any CPU
 		{CF63C942-895A-4F6B-888A-7653D7C4991A}.Release|x86.ActiveCfg = Release|Any CPU
 		{CF63C942-895A-4F6B-888A-7653D7C4991A}.Release|x86.Build.0 = Release|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Debug|arm64.ActiveCfg = Debug|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Debug|arm64.Build.0 = Debug|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Debug|x64.Build.0 = Debug|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Debug|x86.Build.0 = Debug|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Release|Any CPU.Build.0 = Release|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Release|arm64.ActiveCfg = Release|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Release|arm64.Build.0 = Release|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Release|x64.ActiveCfg = Release|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Release|x64.Build.0 = Release|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Release|x86.ActiveCfg = Release|Any CPU
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589}.Release|x86.Build.0 = Release|Any CPU
 		{D53F0EF7-0CDC-49B4-AA2D-229901B0A734}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{D53F0EF7-0CDC-49B4-AA2D-229901B0A734}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{D53F0EF7-0CDC-49B4-AA2D-229901B0A734}.Debug|arm64.ActiveCfg = Debug|Any CPU
@@ -11752,6 +11771,8 @@ Global
 		{2D64CA23-6E81-488E-A7D3-9BDF87240098} = {0F39820F-F4A5-41C6-9809-D79B68F032EF}
 		{2B60E6D3-9E7C-427A-AD4E-BBE9A6D935B9} = {2D64CA23-6E81-488E-A7D3-9BDF87240098}
 		{CF63C942-895A-4F6B-888A-7653D7C4991A} = {2D64CA23-6E81-488E-A7D3-9BDF87240098}
+		{6469F11E-8CEE-4292-820B-324DFFC88EBC} = {0F39820F-F4A5-41C6-9809-D79B68F032EF}
+		{8D2CC6ED-5105-4F52-8757-C21F4DE78589} = {6469F11E-8CEE-4292-820B-324DFFC88EBC}
 		{9DC6B242-457B-4767-A84B-C3D23B76C642} = {2299CCD8-8F9C-4F2B-A633-9BF4DA81022B}
 		{D53F0EF7-0CDC-49B4-AA2D-229901B0A734} = {9DC6B242-457B-4767-A84B-C3D23B76C642}
 	EndGlobalSection

src/Caching/Caching.slnf

@@ -8,6 +8,7 @@
       "src\\Caching\\SqlServer\\test\\Microsoft.Extensions.Caching.SqlServer.Tests.csproj",
       "src\\Caching\\StackExchangeRedis\\src\\Microsoft.Extensions.Caching.StackExchangeRedis.csproj",
       "src\\Caching\\StackExchangeRedis\\test\\Microsoft.Extensions.Caching.StackExchangeRedis.Tests.csproj",
+      "src\\Caching\\perf\\MicroBenchmarks\\Microsoft.Extensions.Caching.MicroBenchmarks\\Microsoft.Extensions.Caching.MicroBenchmarks.csproj",
       "src\\Middleware\\OutputCaching\\src\\Microsoft.AspNetCore.OutputCaching.csproj"
     ]
   }

src/Caching/Hybrid/src/HybridCacheOptions.cs

@@ -6,14 +6,17 @@
 using System.Linq;
 using System.Text;
 using System.Threading.Tasks;
+using Microsoft.Extensions.Options;
 
 namespace Microsoft.Extensions.Caching.Hybrid;
 
 /// <summary>
 /// Options for configuring the default <see cref="HybridCache"/> implementation.
 /// </summary>
-public class HybridCacheOptions
+public class HybridCacheOptions // : IOptions<HybridCacheOptions>
 {
+    // TODO: should we implement IOptions<T>?
+
     /// <summary>
     /// Default global options to be applied to <see cref="HybridCache"/> operations; if options are
     /// specified at the individual call level, the non-null values are merged (with the per-call
@@ -45,4 +48,6 @@ public class HybridCacheOptions
     /// tags do not contain data that should not be visible in metrics systems.
     /// </summary>
     public bool ReportTagMetrics { get; set; }
+
+    // HybridCacheOptions IOptions<HybridCacheOptions>.Value => this;
 }

src/Caching/Hybrid/src/HybridCacheServiceExtensions.cs

@@ -50,7 +50,6 @@ public static IHybridCacheBuilder AddHybridCache(this IServiceCollection service
         services.TryAddSingleton(TimeProvider.System);
         services.AddOptions();
         services.AddMemoryCache();
-        services.AddDistributedMemoryCache(); // we need a backend; use in-proc by default
         services.TryAddSingleton<IHybridCacheSerializerFactory, DefaultJsonSerializerFactory>();
         services.TryAddSingleton<IHybridCacheSerializer<string>>(InbuiltTypeSerializer.Instance);
         services.TryAddSingleton<IHybridCacheSerializer<byte[]>>(InbuiltTypeSerializer.Instance);

src/Caching/Hybrid/src/Internal/BufferChunk.cs

@@ -0,0 +1,77 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Buffers;
+using System.Diagnostics;
+using System.Runtime.CompilerServices;
+
+namespace Microsoft.Extensions.Caching.Hybrid.Internal;
+
+// used to convey buffer status; like ArraySegment<byte>, but Offset is always
+// zero, and we use the MSB of the length to track whether or not to recycle this value
+internal readonly struct BufferChunk
+{
+    private const int MSB = (1 << 31);
+
+    private readonly int _lengthAndPoolFlag;
+    public byte[]? Array { get; } // null for default
+
+    public int Length => _lengthAndPoolFlag & ~MSB;
+
+    public bool ReturnToPool => (_lengthAndPoolFlag & MSB) != 0;
+
+    public byte[] ToArray()
+    {
+        var length = Length;
+        if (length == 0)
+        {
+            return [];
+        }
+
+        var copy = new byte[length];
+        Buffer.BlockCopy(Array!, 0, copy, 0, length);
+        return copy;
+    }
+
+    public BufferChunk(byte[] array)
+    {
+        Debug.Assert(array is not null, "expected valid array input");
+        Array = array;
+        _lengthAndPoolFlag = array.Length;
+        // assume not pooled, if exact-sized
+        Debug.Assert(!ReturnToPool, "do not return right-sized arrays");
+        Debug.Assert(Length == array.Length, "array length not respected");
+    }
+
+    public BufferChunk(byte[] array, int length, bool returnToPool)
+    {
+        Debug.Assert(array is not null, "expected valid array input");
+        Debug.Assert(length >= 0, "expected valid length");
+        Array = array;
+        _lengthAndPoolFlag = length | (returnToPool ? MSB : 0);
+        Debug.Assert(ReturnToPool == returnToPool, "return-to-pool not respected");
+        Debug.Assert(Length == length, "length not respected");
+    }
+
+    internal void RecycleIfAppropriate()
+    {
+        if (ReturnToPool)
+        {
+            ArrayPool<byte>.Shared.Return(Array!);
+        }
+        Unsafe.AsRef(in this) = default; // anti foot-shotgun double-return guard; not 100%, but worth doing
+        Debug.Assert(Array is null && !ReturnToPool, "expected clean slate after recycle");
+    }
+
+    internal ReadOnlySequence<byte> AsSequence() => Length == 0 ? default : new ReadOnlySequence<byte>(Array!, 0, Length);
+
+    internal BufferChunk DoNotReturnToPool()
+    {
+        var copy = this;
+        Unsafe.AsRef(in copy._lengthAndPoolFlag) &= ~MSB;
+        Debug.Assert(copy.Length == Length, "same length expected");
+        Debug.Assert(!copy.ReturnToPool, "do not return to pool");
+        return copy;
+    }
+}

src/Caching/Hybrid/src/Internal/DefaultHybridCache.CacheItem.cs

@@ -0,0 +1,49 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using Microsoft.Extensions.Caching.Memory;
+
+namespace Microsoft.Extensions.Caching.Hybrid.Internal;
+
+partial class DefaultHybridCache
+{
+    internal abstract class CacheItem
+    {
+        internal static readonly PostEvictionDelegate _sharedOnEviction = static (key, value, reason, state) =>
+        {
+            if (value is CacheItem item)
+            {
+                // perform per-item clean-up; this could be buffer recycling (if defensive copies needed),
+                // or could be disposal
+                item.OnEviction();
+            }
+        };
+
+        public virtual void Release() { } // for recycling purposes
+
+        public abstract bool NeedsEvictionCallback { get; } // do we need to call Release when evicted?
+
+        public virtual void OnEviction() { } // only invoked if NeedsEvictionCallback reported true
+
+        public abstract bool TryReserveBuffer(out BufferChunk buffer);
+
+        public abstract bool DebugIsImmutable { get; }
+    }
+
+    internal abstract class CacheItem<T> : CacheItem
+    {
+        public abstract bool TryGetValue(out T value);
+
+        public T GetValue()
+        {
+            if (!TryGetValue(out var value))
+            {
+                Throw();
+            }
+            return value;
+
+            static void Throw() => throw new ObjectDisposedException("The cache item has been recycled before the value was obtained");
+        }
+    }
+}

src/Caching/Hybrid/src/Internal/DefaultHybridCache.Debug.cs

@@ -0,0 +1,70 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+
+namespace Microsoft.Extensions.Caching.Hybrid.Internal;
+
+partial class DefaultHybridCache
+{
+    internal bool DebugTryGetCacheItem(string key, [NotNullWhen(true)] out CacheItem? value)
+    {
+        if (_localCache.TryGetValue(key, out var untyped) && untyped is CacheItem typed)
+        {
+            value = typed;
+            return true;
+        }
+        value = null;
+        return false;
+    }
+
+#if DEBUG // enable ref-counted buffers
+
+    private int _outstandingBufferCount;
+
+    internal int DebugGetOutstandingBuffers(bool flush = false)
+                => flush ? Interlocked.Exchange(ref _outstandingBufferCount, 0) : Volatile.Read(ref _outstandingBufferCount);
+
+    [Conditional("DEBUG")]
+    internal void DebugDecrementOutstandingBuffers()
+    {
+        Interlocked.Decrement(ref _outstandingBufferCount);
+    }
+
+    [Conditional("DEBUG")]
+    internal void DebugIncrementOutstandingBuffers()
+    {
+        Interlocked.Increment(ref _outstandingBufferCount);
+    }
+#endif
+
+    partial class MutableCacheItem<T>
+    {
+        partial void DebugDecrementOutstandingBuffers();
+        partial void DebugTrackBufferCore(DefaultHybridCache cache);
+
+        [Conditional("DEBUG")]
+        internal void DebugTrackBuffer(DefaultHybridCache cache) => DebugTrackBufferCore(cache);
+
+#if DEBUG
+        private DefaultHybridCache? _cache; // for buffer-tracking - only enabled in DEBUG
+        partial void DebugDecrementOutstandingBuffers()
+        {
+            if (_buffer.ReturnToPool)
+            {
+                _cache?.DebugDecrementOutstandingBuffers();
+            }
+        }
+        partial void DebugTrackBufferCore(DefaultHybridCache cache)
+        {
+            _cache = cache;
+            if (_buffer.ReturnToPool)
+            {
+                _cache?.DebugIncrementOutstandingBuffers();
+            }
+        }
+#endif
+    }
+}

src/Caching/Hybrid/src/Internal/DefaultHybridCache.ImmutableCacheItem.cs

@@ -0,0 +1,45 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.Extensions.Caching.Hybrid.Internal;
+
+partial class DefaultHybridCache
+{
+    private sealed class ImmutableCacheItem<T> : CacheItem<T> // used to hold types that do not require defensive copies
+    {
+        private readonly T _value;
+        public ImmutableCacheItem(T value) => _value = value;
+
+        private static ImmutableCacheItem<T>? _sharedDefault;
+
+        // this is only used when the underlying store is disabled; we don't need 100% singleton; "good enough is"
+        public static ImmutableCacheItem<T> Default => _sharedDefault ??= new(default!);
+
+        public override void OnEviction()
+        {
+            var obj = _value as IDisposable;
+            Debug.Assert(obj is not null, "shouldn't be here for non-disposable types");
+            obj?.Dispose();
+        }
+
+        public override bool NeedsEvictionCallback => ImmutableTypeCache<T>.IsDisposable;
+
+        public override bool TryGetValue(out T value)
+        {
+            value = _value;
+            return true; // always available
+        }
+
+        public override bool TryReserveBuffer(out BufferChunk buffer)
+        {
+            buffer = default;
+            return false; // we don't have one to reserve!
+        }
+
+        public override bool DebugIsImmutable => true;
+    }
+}