com.wallstop-studios.dxmessaging 2.1.4 → 2.1.5

package/.llm/skills/performance/cache-eviction-implementation.md

@@ -0,0 +1,340 @@
+---
+title: "Cache Eviction Implementation"
+id: "cache-eviction-implementation"
+category: "performance"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/Cache/Cache.cs"
+      lines: "1-1600"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "caching"
+  - "eviction"
+  - "lru"
+  - "lfu"
+  - "implementation"
+
+complexity:
+  level: "advanced"
+  reasoning: "Requires understanding of cache policies, data structures, and expiration logic"
+
+impact:
+  performance:
+    rating: "high"
+    details: "Provides predictable eviction and O(1) access paths"
+  maintainability:
+    rating: "medium"
+    details: "Centralized cache logic makes behavior explicit"
+  testability:
+    rating: "high"
+    details: "Stats and deterministic policies make behavior testable"
+
+prerequisites:
+  - "Understanding of cache concepts"
+
+dependencies:
+  packages: []
+  skills:
+    - "cache-eviction-policies"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+    dotnet: ">=netstandard2.0"
+
+aliases:
+  - "Cache implementation"
+
+related:
+  - "cache-eviction-policies"
+  - "cache-eviction-builder"
+
+status: "stable"
+---
+
+# Cache Eviction Implementation
+
+> **One-line summary**: Implement a cache with eviction, expiration, and statistics using O(1) data structures.
+
+## Overview
+
+This implementation uses a dictionary for key lookup and a linked list for eviction ordering. Expiration checks are evaluated on access.
+
+## Problem Statement
+
+Caches without eviction or expiration lead to unbounded memory growth or stale data. This implementation provides clear eviction and TTL behavior.
+
+## Solution
+
+### Core Concept
+
+- Dictionary for O(1) lookup
+- Linked list for eviction order
+- Stats for hit/miss/eviction tracking
+- Optional TTL expiration on access or write
+
+### Implementation
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Core.Cache
+{
+    using System;
+    using System.Collections.Generic;
+
+    public enum EvictionPolicy
+    {
+        Lru,
+        Lfu,
+        Slru,
+        Fifo,
+        Random
+    }
+
+    public sealed class CacheOptions<TKey, TValue>
+    {
+        public int MaximumSize { get; set; } = 1000;
+        public EvictionPolicy Policy { get; set; } = EvictionPolicy.Lru;
+        public float? ExpireAfterWriteSeconds { get; set; }
+        public float? ExpireAfterAccessSeconds { get; set; }
+        public bool RecordStats { get; set; }
+        public IEqualityComparer<TKey> KeyComparer { get; set; }
+    }
+
+    public sealed class Cache<TKey, TValue> : IDisposable
+    {
+        private readonly Dictionary<TKey, CacheEntry> entries;
+        private readonly LinkedList<TKey> accessOrder;
+        private readonly CacheOptions<TKey, TValue> options;
+        private readonly object syncLock = new object();
+
+        private long hitCount;
+        private long missCount;
+        private long evictionCount;
+        private bool disposed;
+
+        private sealed class CacheEntry
+        {
+            public TValue Value;
+            public LinkedListNode<TKey> Node;
+            public float WriteTime;
+            public float LastAccessTime;
+            public int AccessCount;
+        }
+
+        internal Cache(CacheOptions<TKey, TValue> options)
+        {
+            this.options = options;
+            IEqualityComparer<TKey> comparer = options.KeyComparer ?? EqualityComparer<TKey>.Default;
+            entries = new Dictionary<TKey, CacheEntry>(options.MaximumSize, comparer);
+            accessOrder = new LinkedList<TKey>();
+        }
+
+        public bool TryGet(TKey key, out TValue value)
+        {
+            if (disposed)
+            {
+                value = default;
+                return false;
+            }
+
+            lock (syncLock)
+            {
+                if (entries.TryGetValue(key, out CacheEntry entry))
+                {
+                    float now = GetCurrentTime();
+
+                    if (IsExpired(entry, now))
+                    {
+                        RemoveEntry(key, entry);
+                        value = default;
+                        missCount++;
+                        return false;
+                    }
+
+                    entry.LastAccessTime = now;
+                    entry.AccessCount++;
+                    PromoteToMru(entry);
+
+                    hitCount++;
+                    value = entry.Value;
+                    return true;
+                }
+
+                missCount++;
+                value = default;
+                return false;
+            }
+        }
+
+        public void Put(TKey key, TValue value)
+        {
+            if (disposed)
+            {
+                return;
+            }
+
+            lock (syncLock)
+            {
+                float now = GetCurrentTime();
+
+                if (entries.TryGetValue(key, out CacheEntry existing))
+                {
+                    existing.Value = value;
+                    existing.WriteTime = now;
+                    existing.LastAccessTime = now;
+                    PromoteToMru(existing);
+                    return;
+                }
+
+                while (entries.Count >= options.MaximumSize)
+                {
+                    EvictOne();
+                }
+
+                LinkedListNode<TKey> node = accessOrder.AddFirst(key);
+                entries[key] = new CacheEntry
+                {
+                    Value = value,
+                    Node = node,
+                    WriteTime = now,
+                    LastAccessTime = now,
+                    AccessCount = 1
+                };
+            }
+        }
+
+        public CacheStats GetStats()
+        {
+            return new CacheStats
+            {
+                HitCount = hitCount,
+                MissCount = missCount,
+                EvictionCount = evictionCount,
+                Size = entries.Count,
+                HitRate = hitCount + missCount > 0
+                    ? (double)hitCount / (hitCount + missCount)
+                    : 0
+            };
+        }
+
+        private void EvictOne()
+        {
+            if (accessOrder.Count == 0)
+            {
+                return;
+            }
+
+            TKey keyToEvict = options.Policy switch
+            {
+                EvictionPolicy.Lru => accessOrder.Last.Value,
+                EvictionPolicy.Fifo => accessOrder.Last.Value,
+                EvictionPolicy.Random => GetRandomKey(),
+                _ => accessOrder.Last.Value
+            };
+
+            if (entries.TryGetValue(keyToEvict, out CacheEntry entry))
+            {
+                RemoveEntry(keyToEvict, entry);
+                evictionCount++;
+            }
+        }
+
+        private void PromoteToMru(CacheEntry entry)
+        {
+            if (options.Policy == EvictionPolicy.Lru || options.Policy == EvictionPolicy.Slru)
+            {
+                accessOrder.Remove(entry.Node);
+                accessOrder.AddFirst(entry.Node);
+            }
+        }
+
+        private bool IsExpired(CacheEntry entry, float now)
+        {
+            if (options.ExpireAfterWriteSeconds.HasValue)
+            {
+                if (now - entry.WriteTime > options.ExpireAfterWriteSeconds.Value)
+                {
+                    return true;
+                }
+            }
+
+            if (options.ExpireAfterAccessSeconds.HasValue)
+            {
+                if (now - entry.LastAccessTime > options.ExpireAfterAccessSeconds.Value)
+                {
+                    return true;
+                }
+            }
+
+            return false;
+        }
+
+        private void RemoveEntry(TKey key, CacheEntry entry)
+        {
+            accessOrder.Remove(entry.Node);
+            entries.Remove(key);
+        }
+
+        private TKey GetRandomKey()
+        {
+            int index = UnityEngine.Random.Range(0, entries.Count);
+            LinkedListNode<TKey> node = accessOrder.First;
+            for (int i = 0; i < index; i++)
+            {
+                node = node.Next;
+            }
+            return node.Value;
+        }
+
+        private static float GetCurrentTime()
+        {
+            return UnityEngine.Time.realtimeSinceStartup;
+        }
+
+        public void Dispose()
+        {
+            disposed = true;
+            lock (syncLock)
+            {
+                entries.Clear();
+                accessOrder.Clear();
+            }
+        }
+    }
+
+    public struct CacheStats
+    {
+        public long HitCount;
+        public long MissCount;
+        public long EvictionCount;
+        public int Size;
+        public double HitRate;
+    }
+}
+```
+
+## See Also
+
+- [High-Performance Cache with Eviction Policies](cache-eviction-policies.md)
+- [Cache Builder Configuration](cache-eviction-builder.md)
+
+## References
+
+- [Cache replacement policies](https://en.wikipedia.org/wiki/Cache_replacement_policies)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-21 | Initial version |

package/.llm/skills/performance/cache-eviction-policies.md

@@ -0,0 +1,176 @@
+---
+title: "High-Performance Cache with Eviction Policies"
+id: "cache-eviction-policies"
+category: "performance"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/Cache/Cache.cs"
+      lines: "1-1600"
+    - path: "Runtime/Core/Cache/CacheBuilder.cs"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "caching"
+  - "memory"
+  - "performance"
+  - "lru"
+  - "lfu"
+  - "eviction"
+  - "data-structures"
+
+complexity:
+  level: "advanced"
+  reasoning: "Requires understanding of cache eviction algorithms and memory trade-offs"
+
+impact:
+  performance:
+    rating: "high"
+    details: "Reduces expensive computation/IO by caching results with intelligent eviction"
+  maintainability:
+    rating: "high"
+    details: "Fluent builder API makes configuration clear"
+  testability:
+    rating: "high"
+    details: "Statistics recording enables cache behavior verification"
+
+prerequisites:
+  - "Understanding of cache concepts"
+  - "Knowledge of LRU/LFU algorithms"
+
+dependencies:
+  packages: []
+  skills: []
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+    dotnet: ">=netstandard2.0"
+
+aliases:
+  - "LRU Cache"
+  - "Memoization cache"
+  - "Result caching"
+
+related:
+  - "object-pooling"
+  - "fluent-builder-pattern"
+  - "cache-eviction-implementation"
+  - "cache-eviction-builder"
+
+status: "stable"
+---
+
+# High-Performance Cache with Eviction Policies
+
+> **One-line summary**: Build production-ready caches with LRU/LFU/SLRU eviction, TTL expiration, and statistics using a fluent builder.
+
+## Overview
+
+A well-designed cache reduces expensive computation or IO by storing results and evicting entries using a predictable policy. This pattern provides:
+
+1. **Multiple eviction policies**: LRU, LFU, SLRU, FIFO, Random
+1. **Time-based expiration**: Expire after write or access
+1. **Size limits**: Maximum entry count with automatic eviction
+1. **Statistics**: Hit/miss rates and eviction counts
+
+## Problem Statement
+
+```csharp
+// BAD: No caching - expensive operation every call
+public GameData LoadGameData(string playerId)
+{
+    return database.Query<GameData>(playerId); // 50ms per call
+}
+
+// BAD: Unbounded cache - memory leak
+private Dictionary<string, GameData> cache = new Dictionary<string, GameData>();
+
+public GameData LoadGameDataCached(string playerId)
+{
+    if (!cache.TryGetValue(playerId, out GameData data))
+    {
+        data = database.Query<GameData>(playerId);
+        cache[playerId] = data; // Grows forever!
+    }
+    return data;
+}
+```
+
+## Solution
+
+### Core Concept
+
+```text
+Cache<K, V>
+- MaxSize: 1000 entries
+- Policy: LRU (Least Recently Used)
+- ExpireAfterWrite: 5 minutes
+- ExpireAfterAccess: 1 minute
+```
+
+### Basic Usage
+
+```csharp
+using Cache<string, GameData> cache = new CacheBuilder<string, GameData>()
+    .WithMaximumSize(1000)
+    .WithPolicy(EvictionPolicy.Lru)
+    .Build();
+
+if (!cache.TryGet(playerId, out GameData data))
+{
+    data = database.Query<GameData>(playerId);
+    cache.Put(playerId, data);
+}
+```
+
+## Eviction Policy Guide
+
+| Policy | Best For             | Characteristics                    |
+| ------ | -------------------- | ---------------------------------- |
+| LRU    | General purpose      | Evicts least recently accessed     |
+| LFU    | Frequency matters    | Evicts least frequently accessed   |
+| SLRU   | Hot/cold data        | Protects frequently accessed items |
+| FIFO   | Time-based freshness | Evicts oldest regardless of access |
+| Random | Simple, uniform      | No tracking overhead               |
+
+## Best Practices
+
+### Do
+
+- Size cache based on entry size and memory budget
+- Enable stats during tuning to pick a policy
+- Choose eviction policy based on access patterns
+- Dispose caches when no longer needed
+
+### Don't
+
+- Don't use unbounded dictionaries as caches
+- Don't cache data that changes too frequently
+- Don't use Random eviction for performance-critical code
+
+## See Also
+
+- [Cache Eviction Implementation](cache-eviction-implementation.md)
+- [Cache Builder Configuration](cache-eviction-builder.md)
+- [Object Pooling](./object-pooling.md)
+- [Fluent Builder Pattern](../solid/fluent-builder-pattern.md)
+
+## References
+
+- [Cache design overview](https://en.wikipedia.org/wiki/Cache_replacement_policies)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-21 | Initial version |