< Summary

Information
Class: AmbientServices.BasicAmbientAtomicCache
Assembly: AmbientServices
File(s): /home/runner/work/AmbientServices/AmbientServices/AmbientServices/DefaultImplementation/BasicAmbientAtomicCache.cs
Tag: 332_35464845198
Line coverage
98%
Covered lines: 270
Uncovered lines: 3
Coverable lines: 273
Total lines: 635
Line coverage: 98.9%
Branch coverage
94%
Covered branches: 160
Total branches: 170
Branch coverage: 94.1%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
.cctor()100%11100%
.ctor(...)100%66100%
.ctor()100%11100%
GetUnversionedStorageKey(...)100%11100%
GetVersionedStorageKey(...)100%11100%
ShouldDisposeWhenDiscarding(...)100%22100%
Create(...)100%88100%
.ctor(...)100%11100%
Dispose()100%22100%
.ctor(...)100%11100%
Dispose()100%11100%
.ctor(...)100%11100%
Dispose()100%22100%
NormalizeExpiresInstant(...)100%66100%
IsExpired(...)100%22100%
ComputeActualExpiration(...)77.78%1818100%
ComputeOptimisticRetryDeadlineUtc(...)100%44100%
ThrowIfOptimisticRetryDeadlineExceeded(...)100%22100%
ThrowIfCancellationUnlessRetryDeadlineExceeded(...)100%2275%
EnqueueExpiration(...)100%22100%
DisposeDiscardedValue()75%44100%
get_IsShared()100%11100%
GetOrAdd()92.86%141494.74%
AddOrUpdate()100%1818100%
Remove()100%22100%
VersionedRemove()100%22100%
VersionedGet()100%88100%
VersionedPut()94.44%1818100%
EjectIfNeeded()90%1010100%
EjectOneTimed()94.44%1818100%
EjectOneUntimed()100%1010100%
EjectEntry()100%22100%
Clear()87.5%88100%

File(s)

/home/runner/work/AmbientServices/AmbientServices/AmbientServices/DefaultImplementation/BasicAmbientAtomicCache.cs

#LineLine coverage
 1using System;
 2using System.Collections.Concurrent;
 3using System.Collections.Generic;
 4using System.Threading;
 5using System.Threading.Tasks;
 6
 7namespace AmbientServices;
 8
 9/// <summary>
 10/// Default in-process implementation of <see cref="IAmbientAtomicCache"/> using concurrent dictionaries and optimistic 
 11/// </summary>
 12/// <remarks>
 13/// <pitch>The zero-configuration atomic cache used unless overridden: a single-process realization (<see cref="IsShared
 14/// <pledge><see cref="IAmbientAtomicCache"/></pledge>
 15/// <pledge>Optimistic add/update retries are capped at thirty seconds of <see cref="AmbientClock"/> time, shortened fur
 16/// <pledge>Because <see cref="IsShared"/> is false, disposable values are permitted, and dispose responsibility is infe
 17/// <plan>
 18/// One <see cref="ConcurrentDictionary{TKey,TValue}"/> holds both operation families, with single-character storage-key
 19/// Installs are compare-and-swap loops over TryAdd/TryUpdate: factories run outside any lock, losers are disposed via a
 20/// Disposal is driven off a type test taken when the entry is built, so the cache disposes a losing factory result, a r
 21/// A displaced versioned entry is disposed once, awaited, outside the dictionary rather than inside an update delegate,
 22/// Caller timeouts are realized by linking the caller's token to an <see cref="AmbientCancellationTokenSource"/> (an al
 23/// Size is bounded by the same timed/untimed queue bookkeeping, cadence-driven ejection, and bounded <see cref="Clear"/
 24/// Trade-offs: no cross-process sharing or durability, approximate size bounds, and duplicate factory work under conten
 25/// </plan>
 26/// <priority>
 27/// <see cref="IAmbientAtomicCache"/>
 28/// 1. Sharing the local cache's bookkeeping over tuning its own: size bounding reuses <see cref="BasicAmbientLocalCache
 29/// </priority>
 30/// <para>Bounded size is enforced by ejecting timed and untimed bookkeeping rows on a configurable cadence.  Settings u
 31/// <para>Expiration comparisons and optimistic retry deadlines use <see cref="AmbientClock"/> so tests can pause or ski
 32/// <para><see cref="Clear"/> snapshots the cache and ejects each entry in a bounded number of passes.  Concurrent insta
 33/// </remarks>
 34[DefaultAmbientService]
 35internal class BasicAmbientAtomicCache : IAmbientAtomicCache
 36{
 37    /// <summary>Distinct one-char prefix so unversioned and versioned logical keys never share one dictionary slot.</su
 38    private const string UnversionedStorageKeyPrefix = "N";
 39
 40    /// <summary>Distinct one-char prefix so unversioned and versioned logical keys never share one dictionary slot.</su
 41    private const string VersionedStorageKeyPrefix = "V";
 42
 43    /// <summary>Wall-clock budget for optimistic <see cref="GetOrAdd{T}"/> / <see cref="AddOrUpdate{T}"/> CAS-style ret
 244    private static readonly TimeSpan MaxOptimisticRetryDuration = TimeSpan.FromSeconds(30);
 45
 46    private const string OptimisticRetryBudgetExceededMessage = "The atomic cache optimistic retry budget was exceeded."
 47
 48    /// <summary>Caps stale-queue draining per eject call so a pathological queue cannot spin unbounded in one async con
 49    private const int MaxEjectQueueDrainSteps = 65536;
 50
 51    /// <summary>Maximum snapshot-and-eject passes in <see cref="Clear"/> before giving up on reaching an empty cache.</
 52    private const int MaxClearPasses = 8;
 53
 254    private static readonly AmbientService<IAmbientSettingsSet> _Settings = Ambient.GetService<IAmbientSettingsSet>();
 55
 56    private readonly IAmbientSetting<int> _callFrequencyToEject;
 57    private readonly IAmbientSetting<int> _countToEject;
 58    private readonly IAmbientSetting<int> _minCacheEntries;
 59    private int _expireCount;
 260    private ConcurrentQueue<TimedQueueEntry> _timedQueue = new();   // interlocked (make readonly when we no longer supp
 261    private ConcurrentQueue<string> _untimedQueue = new();          // interlocked (make readonly when we no longer supp
 262    private readonly ConcurrentDictionary<string, CacheEntry> _cache = new();
 263    private readonly ConcurrentDictionary<string, VersionCounter> _versionCounters = new();
 64
 65    private sealed class VersionCounter
 66    {
 67        internal long Last;
 68    }
 69
 70    public BasicAmbientAtomicCache()
 271        : this(_Settings.Local)
 72    {
 273    }
 74
 275    public BasicAmbientAtomicCache(IAmbientSettingsSet? settings)
 76    {
 277        _callFrequencyToEject = AmbientSettings.GetSetting<int>(settings, nameof(BasicAmbientAtomicCache) + "-EjectFrequ
 278        _countToEject = AmbientSettings.GetSetting<int>(settings, nameof(BasicAmbientAtomicCache) + "-MaximumItemCount",
 279        _minCacheEntries = AmbientSettings.GetSetting<int>(settings, nameof(BasicAmbientAtomicCache) + "-MinimumItemCoun
 280    }
 81
 282    private static string GetUnversionedStorageKey(string itemKey) => UnversionedStorageKeyPrefix + itemKey;
 83
 284    private static string GetVersionedStorageKey(string itemKey) => VersionedStorageKeyPrefix + itemKey;
 85
 86    private struct TimedQueueEntry
 87    {
 88        public string Key;
 89        public DateTime Expiration;
 90    }
 91
 92    private static bool ShouldDisposeWhenDiscarding(object entry)
 93    {
 294        return entry is IAsyncDisposable || entry is IDisposable;
 95    }
 96
 97    private readonly struct TimeoutCancellationRegistration : IDisposable
 98    {
 99        public CancellationToken Token { get; }
 100        private readonly IDisposable? _cleanup;
 101
 102        public static TimeoutCancellationRegistration Create(TimeSpan? timeout, CancellationToken cancel)
 103        {
 2104            if (timeout is not TimeSpan to)
 105            {
 2106                return new TimeoutCancellationRegistration(null, cancel);
 107            }
 108
 109            // System.Timers.Timer rejects non-positive intervals; use an already-cancelled CTS for "elapsed now" budget
 2110            if (to <= TimeSpan.Zero)
 111            {
 112#pragma warning disable CA2000 // dispose ownership transferred to TimeoutCancellationRegistration or linked CTS
 2113                CancellationTokenSource immediateTimeout = new();
 114#pragma warning restore CA2000
 2115                immediateTimeout.Cancel();
 2116                if (!cancel.CanBeCanceled)
 117                {
 2118                    return new TimeoutCancellationRegistration(immediateTimeout, immediateTimeout.Token);
 119                }
 120
 2121                CancellationTokenSource linkedImmediateTimeout = CancellationTokenSource.CreateLinkedTokenSource(cancel,
 2122                return new TimeoutCancellationRegistration(linkedImmediateTimeout, linkedImmediateTimeout.Token);
 123            }
 124
 2125            AmbientCancellationTokenSource ambientTimeout = new(to);
 2126            if (!cancel.CanBeCanceled)
 127            {
 2128                return new TimeoutCancellationRegistration(ambientTimeout, ambientTimeout.Token);
 129            }
 130
 2131            CancellationTokenSource linkedAmbientTimeout = CancellationTokenSource.CreateLinkedTokenSource(cancel, ambie
 2132            return new TimeoutCancellationRegistration(new TimeoutCleanup(linkedAmbientTimeout, ambientTimeout), linkedA
 133        }
 134
 135        private TimeoutCancellationRegistration(IDisposable? cleanup, CancellationToken token)
 136        {
 2137            Token = token;
 2138            _cleanup = cleanup;
 2139        }
 140
 2141        public void Dispose() => _cleanup?.Dispose();
 142    }
 143
 144    private sealed class TimeoutCleanup : IDisposable
 145    {
 146        private readonly CancellationTokenSource _linked;
 147        private readonly AmbientCancellationTokenSource _ambient;
 148
 2149        public TimeoutCleanup(CancellationTokenSource linked, AmbientCancellationTokenSource ambient)
 150        {
 2151            _linked = linked;
 2152            _ambient = ambient;
 2153        }
 154
 155        public void Dispose()
 156        {
 2157            _linked.Dispose();
 2158            _ambient.Dispose();
 2159        }
 160    }
 161
 162    private class CacheEntry
 163    {
 164        public bool DisposeWhenDiscarding { get; private set; }
 165        public string Key;
 166        public DateTime? Expiration;
 167        public object Entry;
 168        /// <summary>Monotonic revision for versioned storage keys; 0 for non-versioned atomic entries.</summary>
 169        public long MonotonicRevision;
 170
 2171        public CacheEntry(string key, DateTime? expiration, object entry, bool disposeWhenDiscarding, long monotonicRevi
 172        {
 2173            DisposeWhenDiscarding = disposeWhenDiscarding;
 2174            Key = key;
 2175            Expiration = expiration;
 2176            Entry = entry;
 2177            MonotonicRevision = monotonicRevision;
 2178        }
 179        public async ValueTask Dispose()
 180        {
 181            // if the entry is disposable, dispose it after removing it
 2182            if (DisposeWhenDiscarding) await DisposeDiscardedValue(Entry);
 2183        }
 184    }
 185
 186    private static DateTime? NormalizeExpiresInstant(DateTime? expires)
 187    {
 2188        if (expires == null) return null;
 2189        DateTime e = expires.Value;
 2190        if (e.Kind == DateTimeKind.Local) return e.ToUniversalTime();
 2191        if (e.Kind == DateTimeKind.Unspecified) return DateTime.SpecifyKind(e, DateTimeKind.Utc);
 2192        return e;
 193    }
 194
 2195    private static bool IsExpired(CacheEntry entry, DateTime nowUtc) => entry.Expiration < nowUtc;
 196
 197    private static DateTime? ComputeActualExpiration(TimeSpan? maxCacheDuration, DateTime? expiration, DateTime utcNow)
 198    {
 2199        if (maxCacheDuration < TimeSpan.FromTicks(0)) return null;
 2200        DateTime? actualExpiration = null;
 2201        if (maxCacheDuration != null) actualExpiration = utcNow.Add(maxCacheDuration.Value);
 2202        if (expiration != null)
 203        {
 2204            DateTime exp = expiration.Value;
 2205            if (exp.Kind == DateTimeKind.Local) exp = exp.ToUniversalTime();
 2206            else if (exp.Kind == DateTimeKind.Unspecified) exp = DateTime.SpecifyKind(exp, DateTimeKind.Utc);
 2207            if (actualExpiration == null || exp < actualExpiration) actualExpiration = exp;
 208        }
 2209        return actualExpiration;
 210    }
 211
 212    private static DateTime ComputeOptimisticRetryDeadlineUtc(TimeSpan? operationTimeout)
 213    {
 2214        DateTime utcNow = AmbientClock.UtcNow;
 2215        DateTime deadline = utcNow.Add(MaxOptimisticRetryDuration);
 2216        if (operationTimeout is TimeSpan to)
 217        {
 2218            DateTime byCallerTimeout = utcNow.Add(to);
 2219            if (byCallerTimeout < deadline)
 220            {
 2221                deadline = byCallerTimeout;
 222            }
 223        }
 224
 2225        return deadline;
 226    }
 227
 228    private static void ThrowIfOptimisticRetryDeadlineExceeded(DateTime deadlineUtc)
 229    {
 2230        if (AmbientClock.UtcNow >= deadlineUtc)
 2231            throw new InvalidOperationException(OptimisticRetryBudgetExceededMessage);
 2232    }
 233
 234    /// <summary>
 235    /// If the token is already canceled only because the optimistic-retry window elapsed (ambient clock),
 236    /// throw <see cref="InvalidOperationException"/> instead of <see cref="OperationCanceledException"/> so callers
 237    /// do not treat policy timeout as cooperative cancellation.
 238    /// </summary>
 239    private static void ThrowIfCancellationUnlessRetryDeadlineExceeded(DateTime optimisticRetryDeadlineUtc, Cancellation
 240    {
 2241        if (!effectiveCancel.IsCancellationRequested) return;
 2242        ThrowIfOptimisticRetryDeadlineExceeded(optimisticRetryDeadlineUtc);
 2243        effectiveCancel.ThrowIfCancellationRequested();
 0244    }
 245
 246    private void EnqueueExpiration(string storageKey, DateTime? actualExpiration)
 247    {
 2248        if (actualExpiration == null)
 249        {
 2250            _untimedQueue.Enqueue(storageKey);
 251        }
 252        else
 253        {
 2254            _timedQueue.Enqueue(new TimedQueueEntry { Key = storageKey, Expiration = actualExpiration.Value });
 255        }
 2256    }
 257
 258    /// <summary>
 259    /// Disposes a value the cache is discarding, preferring asynchronous disposal when the value implements both interf
 260    /// </summary>
 261    private static async ValueTask DisposeDiscardedValue(object value)
 262    {
 2263        if (value is IAsyncDisposable asyncDisposable) await asyncDisposable.DisposeAsync();
 2264        else if (value is IDisposable disposable) disposable.Dispose();
 2265    }
 266
 267    /// <inheritdoc/>
 2268    public bool IsShared => false;
 269
 270    /// <inheritdoc/>
 271    public async ValueTask<T> GetOrAdd<T>(string itemKey, Func<ValueTask<(T Item, DateTime? Expires)>> create, TimeSpan?
 272    {
 2273        using TimeoutCancellationRegistration timeoutRegistration = TimeoutCancellationRegistration.Create(timeout, canc
 2274        CancellationToken effectiveCancel = timeoutRegistration.Token;
 2275        string storageKey = GetUnversionedStorageKey(itemKey);
 2276        DateTime optimisticRetryDeadlineUtc = ComputeOptimisticRetryDeadlineUtc(timeout);
 2277        while (AmbientClock.UtcNow < optimisticRetryDeadlineUtc)
 278        {
 2279            ThrowIfOptimisticRetryDeadlineExceeded(optimisticRetryDeadlineUtc);
 2280            ThrowIfCancellationUnlessRetryDeadlineExceeded(optimisticRetryDeadlineUtc, effectiveCancel);
 2281            DateTime now = AmbientClock.UtcNow;
 2282            if (_cache.TryGetValue(storageKey, out CacheEntry? entry))
 283            {
 2284                if (!IsExpired(entry, now))
 285                {
 2286                    if (refresh != null)
 287                    {
 2288                        DateTime newExpiration = now.Add(refresh.Value);
 2289                        entry.Expiration = newExpiration;
 2290                        _timedQueue.Enqueue(new TimedQueueEntry { Key = storageKey, Expiration = newExpiration });
 291                    }
 2292                    await EjectIfNeeded();
 2293                    return (T)entry.Entry;
 294                }
 2295                await EjectEntry(entry);
 2296                ThrowIfOptimisticRetryDeadlineExceeded(optimisticRetryDeadlineUtc);
 297            }
 298            else
 299            {
 2300                await EjectIfNeeded();
 2301                ThrowIfOptimisticRetryDeadlineExceeded(optimisticRetryDeadlineUtc);
 302            }
 303
 2304            (T created, DateTime? expires) = await create();
 2305            ThrowIfOptimisticRetryDeadlineExceeded(optimisticRetryDeadlineUtc);
 2306            DateTime? actualExpiration = NormalizeExpiresInstant(expires);
 2307            DateTime nowAfterCreate = AmbientClock.UtcNow;
 2308            if (actualExpiration < nowAfterCreate)
 309            {
 2310                await DisposeDiscardedValue(created);
 2311                ThrowIfOptimisticRetryDeadlineExceeded(optimisticRetryDeadlineUtc);
 2312                ThrowIfCancellationUnlessRetryDeadlineExceeded(optimisticRetryDeadlineUtc, effectiveCancel);
 2313                continue;
 314            }
 315
 2316            CacheEntry newEntry = new(storageKey, actualExpiration, created, ShouldDisposeWhenDiscarding(created));
 2317            if (_cache.TryAdd(storageKey, newEntry))
 318            {
 2319                EnqueueExpiration(storageKey, actualExpiration);
 2320                await EjectIfNeeded();
 2321                return created;
 322            }
 323
 0324            await DisposeDiscardedValue(created);
 0325        }
 326
 2327        throw new InvalidOperationException(OptimisticRetryBudgetExceededMessage);
 2328    }
 329
 330    /// <inheritdoc/>
 331    public async ValueTask<T> AddOrUpdate<T>(string itemKey, Func<ValueTask<(T Item, DateTime? Expires)>> create, Func<T
 332    {
 2333        using TimeoutCancellationRegistration timeoutRegistration = TimeoutCancellationRegistration.Create(timeout, canc
 2334        CancellationToken effectiveCancel = timeoutRegistration.Token;
 2335        string storageKey = GetUnversionedStorageKey(itemKey);
 2336        DateTime optimisticRetryDeadlineUtc = ComputeOptimisticRetryDeadlineUtc(timeout);
 2337        while (AmbientClock.UtcNow < optimisticRetryDeadlineUtc)
 338        {
 2339            ThrowIfOptimisticRetryDeadlineExceeded(optimisticRetryDeadlineUtc);
 2340            ThrowIfCancellationUnlessRetryDeadlineExceeded(optimisticRetryDeadlineUtc, effectiveCancel);
 2341            DateTime now = AmbientClock.UtcNow;
 2342            if (_cache.TryGetValue(storageKey, out CacheEntry? existing))
 343            {
 2344                if (IsExpired(existing, now))
 345                {
 2346                    await EjectEntry(existing);
 2347                    ThrowIfOptimisticRetryDeadlineExceeded(optimisticRetryDeadlineUtc);
 348                }
 349                else
 350                {
 2351                    T current = (T)existing.Entry;
 2352                    (T updatedItem, DateTime? expires) = await update(current);
 2353                    ThrowIfOptimisticRetryDeadlineExceeded(optimisticRetryDeadlineUtc);
 2354                    DateTime? actualExpiration = NormalizeExpiresInstant(expires);
 2355                    DateTime nowAfterUpdate = AmbientClock.UtcNow;
 2356                    if (actualExpiration < nowAfterUpdate)
 357                    {
 2358                        await DisposeDiscardedValue(updatedItem);
 2359                        await EjectEntry(existing);
 2360                        ThrowIfOptimisticRetryDeadlineExceeded(optimisticRetryDeadlineUtc);
 2361                        ThrowIfCancellationUnlessRetryDeadlineExceeded(optimisticRetryDeadlineUtc, effectiveCancel);
 2362                        continue;
 363                    }
 364
 2365                    CacheEntry replacement = new(storageKey, actualExpiration, updatedItem, ShouldDisposeWhenDiscarding(
 2366                    if (_cache.TryUpdate(storageKey, replacement, existing))
 367                    {
 2368                        EnqueueExpiration(storageKey, actualExpiration);
 2369                        await EjectIfNeeded();
 2370                        return updatedItem;
 371                    }
 2372                    await DisposeDiscardedValue(updatedItem);
 2373                    continue;
 374                }
 375            }
 376
 2377            (T created, DateTime? createExpires) = await create();
 2378            ThrowIfOptimisticRetryDeadlineExceeded(optimisticRetryDeadlineUtc);
 2379            DateTime? createActualExpiration = NormalizeExpiresInstant(createExpires);
 2380            DateTime nowAfterCreate = AmbientClock.UtcNow;
 2381            if (createActualExpiration < nowAfterCreate)
 382            {
 2383                await DisposeDiscardedValue(created);
 2384                ThrowIfOptimisticRetryDeadlineExceeded(optimisticRetryDeadlineUtc);
 2385                ThrowIfCancellationUnlessRetryDeadlineExceeded(optimisticRetryDeadlineUtc, effectiveCancel);
 2386                continue;
 387            }
 388
 2389            CacheEntry newEntry = new(storageKey, createActualExpiration, created, ShouldDisposeWhenDiscarding(created))
 2390            if (_cache.TryAdd(storageKey, newEntry))
 391            {
 2392                EnqueueExpiration(storageKey, createActualExpiration);
 2393                await EjectIfNeeded();
 2394                return created;
 395            }
 396
 2397            await DisposeDiscardedValue(created);
 2398        }
 399
 2400        throw new InvalidOperationException(OptimisticRetryBudgetExceededMessage);
 2401    }
 402
 403    /// <inheritdoc/>
 404    public async ValueTask Remove<T>(string itemKey, CancellationToken cancel = default)
 405    {
 2406        if (_cache.TryRemove(GetUnversionedStorageKey(itemKey), out CacheEntry? disposeEntry))
 407        {
 2408            await disposeEntry!.Dispose();
 409        }
 2410    }
 411
 412    /// <inheritdoc/>
 413    public async ValueTask VersionedRemove<T>(string itemKey, CancellationToken cancel = default)
 414    {
 2415        if (_cache.TryRemove(GetVersionedStorageKey(itemKey), out CacheEntry? disposeEntry))
 416        {
 2417            await disposeEntry!.Dispose();
 418        }
 2419    }
 420
 421    /// <inheritdoc/>
 422    public async ValueTask<(T? Value, long Version)> VersionedGet<T>(string itemKey, long minVersion = -1, TimeSpan? ref
 423    {
 2424        string storageKey = GetVersionedStorageKey(itemKey);
 2425        using TimeoutCancellationRegistration timeoutRegistration = TimeoutCancellationRegistration.Create(timeout, canc
 2426        CancellationToken effectiveCancel = timeoutRegistration.Token;
 2427        if (!_cache.TryGetValue(storageKey, out CacheEntry? entry))
 428        {
 2429            return (default, 0);
 430        }
 431
 2432        effectiveCancel.ThrowIfCancellationRequested();
 2433        DateTime now = AmbientClock.UtcNow;
 2434        if (IsExpired(entry, now))
 435        {
 2436            await EjectEntry(entry);
 2437            return (default, 0);
 438        }
 439
 2440        if (entry.MonotonicRevision < minVersion)
 441        {
 2442            return (default, entry.MonotonicRevision);
 443        }
 444
 2445        if (refresh != null)
 446        {
 2447            DateTime newExpiration = now.Add(refresh.Value);
 2448            entry.Expiration = newExpiration;
 2449            _timedQueue.Enqueue(new TimedQueueEntry { Key = storageKey, Expiration = newExpiration });
 450        }
 2451        await EjectIfNeeded();
 2452        return ((T)entry.Entry, entry.MonotonicRevision);
 2453    }
 454
 455    /// <inheritdoc/>
 456    public async ValueTask<long> VersionedPut<T>(string itemKey, T value, TimeSpan? maxCacheDuration = null, DateTime? e
 457    {
 2458        if (maxCacheDuration < TimeSpan.FromTicks(0))
 459        {
 2460            await DisposeDiscardedValue(value);
 2461            return 0;
 462        }
 463
 2464        string storageKey = GetVersionedStorageKey(itemKey);
 2465        using TimeoutCancellationRegistration timeoutRegistration = TimeoutCancellationRegistration.Create(timeout, canc
 2466        CancellationToken effectiveCancel = timeoutRegistration.Token;
 2467        DateTime utcNow = AmbientClock.UtcNow;
 2468        DateTime? actualExpiration = ComputeActualExpiration(maxCacheDuration, expiration, utcNow);
 2469        if (actualExpiration < utcNow)
 470        {
 2471            await DisposeDiscardedValue(value);
 2472            return 0;
 473        }
 474
 2475        effectiveCancel.ThrowIfCancellationRequested();
 476
 2477        VersionCounter vc = _versionCounters.GetOrAdd(itemKey, _ => new VersionCounter());
 2478        long revision = Interlocked.Increment(ref vc.Last);
 2479        CacheEntry newEntry = new(storageKey, actualExpiration, value, ShouldDisposeWhenDiscarding(value), revision);
 480        // ConcurrentDictionary has no async update delegate, and its update delegate may run more than
 481        // once under contention — so a disposing side effect there can double-dispose. Do the compare-and-swap
 482        // ourselves: this displaces exactly one entry, which we then dispose once, awaited, outside the dictionary.
 2483        CacheEntry? displaced = null;
 484        while (true)
 485        {
 2486            if (_cache.TryGetValue(storageKey, out CacheEntry? old))
 487            {
 2488                if (_cache.TryUpdate(storageKey, newEntry, old))
 489                {
 2490                    displaced = old;
 2491                    break;
 492                }
 493            }
 2494            else if (_cache.TryAdd(storageKey, newEntry))
 495            {
 496                break;
 497            }
 498            // another writer changed the slot first; re-read and retry
 499        }
 2500        if (displaced != null) await displaced.Dispose();
 2501        EnqueueExpiration(storageKey, actualExpiration);
 2502        await EjectIfNeeded();
 2503        return revision;
 2504    }
 505
 506    private async ValueTask EjectIfNeeded()
 507    {
 2508        int callFrequencyToEject = _callFrequencyToEject.Value;
 2509        if (callFrequencyToEject <= 0)
 2510            callFrequencyToEject = 1;
 511
 2512        int countToEject = _countToEject.Value;
 513        // One increment per cache operation (not per inner eject round): the previous loop incremented on every
 514        // pressure-driven iteration which inflated the cadence counter and could spin unbounded under concurrency
 515        // when queue bookkeeping lagged cache entries (ConcurrentQueue.Count is approximate) or ejection could not
 516        // shrink the queues in one pass.
 2517        int opSerial = Interlocked.Increment(ref _expireCount);
 2518        bool onCadence = (opSerial % callFrequencyToEject) == 0;
 2519        int queueSum = _untimedQueue.Count + _timedQueue.Count;
 2520        bool overCapacity = queueSum > countToEject;
 2521        if (!onCadence && !overCapacity)
 2522            return;
 523
 2524        int maxRounds = Math.Max(32, Math.Min(131072, 4 + 2 * Math.Max(queueSum, countToEject + 1)));
 2525        for (int round = 0; round < maxRounds; round++)
 526        {
 2527            await EjectOneTimed();
 2528            await EjectOneUntimed();
 529
 2530            queueSum = _untimedQueue.Count + _timedQueue.Count;
 2531            if (queueSum <= countToEject)
 532                break;
 533        }
 2534    }
 535
 536    private async ValueTask EjectOneTimed()
 537    {
 538        // have we hit the minimum number of items?
 2539        if (_timedQueue.Count <= _minCacheEntries.Value) return;
 540        // removing at least one timed item (as well as any expired items we come across)
 2541        bool unexpiredItemEjected = false;
 2542        int steps = 0;
 2543        while (steps++ < MaxEjectQueueDrainSteps && _timedQueue.TryDequeue(out TimedQueueEntry qEntry))
 544        {
 545            // Eject only when the cache still has this key with the same expiration as when the row was enqueued (other
 2546            if (_cache.TryGetValue(qEntry.Key, out CacheEntry? entry) && qEntry.Expiration == entry.Expiration)
 547            {
 548                // remove it from the cache, even though it may not have expired yet because it's time to eject somethin
 2549                await EjectEntry(entry);
 550                // fall through and check to see if the next item is already expired
 2551                unexpiredItemEjected = true;
 552            }
 553            // stale queue row or missing cache entry: if we have already ejected an unexpired item, check for another e
 2554            else if (!unexpiredItemEjected)
 555            {
 556                continue;
 557            }
 558            // peek at the next entry
 2559            if (_timedQueue.TryPeek(out qEntry))
 560            {
 561                // has this entry expired? continue looping so that we remove this one too, even though we didn't *have*
 2562                if (qEntry.Expiration < AmbientClock.UtcNow) continue;
 563                // else the entry hasn't expired and we either removed an entry above or skipped this code, so we can ju
 564            }
 565            // if we get here, there is no reason to look at another timed entry
 566            break;
 567        }
 2568    }
 569
 570    private async ValueTask EjectOneUntimed()
 571    {
 572        // have we hit the minimum number of items?
 2573        if (_untimedQueue.Count <= _minCacheEntries.Value) return;
 574        // remove one untimed entry
 2575        int steps = 0;
 2576        while (steps++ < MaxEjectQueueDrainSteps && _untimedQueue.TryDequeue(out string? key))
 577        {
 578            // can we find this item in the cache?
 2579            if (_cache.TryGetValue(key, out CacheEntry? entry))
 580            {
 581                // is the expiration still the same (ie. untimed)?
 2582                if (entry.Expiration == null)
 583                {
 584                    // remove it from the cache
 2585                    await EjectEntry(entry);
 586                    // fall through and stop looping
 587                }
 588                else // else the item was refreshed, so we should ignore this entry and go around again to remove anothe
 589                {
 590                    continue;
 591                }
 592            }
 593            // else we couldn't find the entry in the cache, so just move to the next entry
 594            else
 595            {
 596                continue;
 597            }
 598            // if we get here, there is no reason to look at another untimed entry
 599            break;
 600        }
 2601    }
 602
 603    private async ValueTask EjectEntry(CacheEntry entry)
 604    {
 605        // race to remove the item from the cache--did we win the race?
 2606        if (_cache.TryRemove(entry.Key, out CacheEntry? disposeEntry))
 607        {
 2608            await disposeEntry.Dispose();
 609        }
 2610    }
 611
 612    /// <inheritdoc/>
 613    public async ValueTask Clear(CancellationToken cancel = default)
 614    {
 2615        Interlocked.Exchange(ref _untimedQueue, new ConcurrentQueue<string>());
 2616        Interlocked.Exchange(ref _timedQueue, new ConcurrentQueue<TimedQueueEntry>());
 2617        _versionCounters.Clear();
 618
 2619        for (int pass = 0; pass < MaxClearPasses; pass++)
 620        {
 2621            KeyValuePair<string, CacheEntry>[] snapshot = _cache.ToArray();
 2622            if (snapshot.Length == 0)
 623                break;
 624
 2625            foreach (KeyValuePair<string, CacheEntry> kv in snapshot)
 626            {
 2627                cancel.ThrowIfCancellationRequested();
 2628                await EjectEntry(kv.Value);
 629            }
 630
 2631            if (_cache.IsEmpty)
 632                break;
 633        }
 2634    }
 635}
Generated by: ReportGenerator 5.5.11.0
09/19/2026 - 19:43:36
GitHub | reportgenerator.io

Methods/Properties

.cctor()
.ctor(AmbientServices.IAmbientSettingsSet)
.ctor()
GetUnversionedStorageKey(string)
GetVersionedStorageKey(string)
ShouldDisposeWhenDiscarding(object)
Create(System.Nullable<System.TimeSpan>, System.Threading.CancellationToken)
.ctor(System.IDisposable, System.Threading.CancellationToken)
Dispose()
.ctor(System.Threading.CancellationTokenSource, AmbientServices.AmbientCancellationTokenSource)
Dispose()
.ctor(string, System.Nullable<System.DateTime>, object, bool, long)
Dispose()
NormalizeExpiresInstant(System.Nullable<System.DateTime>)
IsExpired(AmbientServices.BasicAmbientAtomicCache.CacheEntry, System.DateTime)
ComputeActualExpiration(System.Nullable<System.TimeSpan>, System.Nullable<System.DateTime>, System.DateTime)
ComputeOptimisticRetryDeadlineUtc(System.Nullable<System.TimeSpan>)
ThrowIfOptimisticRetryDeadlineExceeded(System.DateTime)
ThrowIfCancellationUnlessRetryDeadlineExceeded(System.DateTime, System.Threading.CancellationToken)
EnqueueExpiration(string, System.Nullable<System.DateTime>)
DisposeDiscardedValue()
get_IsShared()
GetOrAdd()
AddOrUpdate()
Remove()
VersionedRemove()
VersionedGet()
VersionedPut()
EjectIfNeeded()
EjectOneTimed()
EjectOneUntimed()
EjectEntry()
Clear()