com.wallstop-studios.dxmessaging 2.1.7 → 2.1.8

package/.llm/skills/performance/stringbuilder-pooling.md

@@ -1,319 +0,0 @@
----
-title: "StringBuilder Pooling for Zero-Allocation String Building"
-id: "stringbuilder-pooling"
-category: "performance"
-version: "1.0.0"
-created: "2026-01-21"
-updated: "2026-01-21"
-
-source:
-  repository: "wallstop/unity-helpers"
-  files:
-    - path: "Runtime/Utils/Buffers.cs"
-      lines: "148-188"
-  url: "https://github.com/wallstop/unity-helpers"
-
-tags:
-  - "memory"
-  - "allocation"
-  - "pooling"
-  - "zero-alloc"
-  - "strings"
-  - "stringbuilder"
-
-complexity:
-  level: "basic"
-  reasoning: "Simple pattern with clear usage; StringBuilder is well-known"
-
-impact:
-  performance:
-    rating: "high"
-    details: "Eliminates O(n²) string allocations in concatenation loops"
-  maintainability:
-    rating: "high"
-    details: "Cleaner than manual StringBuilder management"
-  testability:
-    rating: "high"
-    details: "String output can be tested directly"
-
-prerequisites:
-  - "Understanding of StringBuilder"
-
-dependencies:
-  packages: []
-  skills:
-    - "collection-pooling"
-
-applies_to:
-  languages:
-    - "C#"
-  frameworks:
-    - "Unity"
-    - ".NET"
-  versions:
-    unity: ">=2021.3"
-    dotnet: ">=netstandard2.0"
-
-aliases:
-  - "String concatenation optimization"
-  - "StringBuffer pooling"
-
-related:
-  - "collection-pooling"
-  - "object-pooling"
-
-status: "stable"
----
-
-# StringBuilder Pooling for Zero-Allocation String Building
-
-> **One-line summary**: Pool StringBuilder instances to eliminate per-operation allocations when building strings in hot paths.
-
-## Overview
-
-String concatenation with `+` or `+=` creates new string objects for each operation, causing O(n²) allocations for n concatenations. StringBuilder avoids this, but creating a new StringBuilder each time still allocates. Pooling StringBuilders eliminates even that allocation.
-
-## Problem Statement
-
-```csharp
-// BAD: O(n²) allocations
-public string BuildItemList(List<Item> items)
-{
-    string result = "";
-    for (int i = 0; i < items.Count; i++)
-    {
-        result += items[i].Name; // New string EACH iteration
-        if (i < items.Count - 1)
-        {
-            result += ", "; // Another allocation
-        }
-    }
-    return result;
-}
-```
-
-For 100 items, this creates ~199 temporary strings that immediately become garbage.
-
-```csharp
-// BETTER but still allocates StringBuilder
-public string BuildItemList(List<Item> items)
-{
-    StringBuilder sb = new StringBuilder(256); // Allocates ~256 bytes
-    // ... build string ...
-    return sb.ToString();
-}
-```
-
-## Solution
-
-### Core Concept
-
-Pool StringBuilders and clear them on return:
-
-```text
-┌────────────────────────────────────────┐
-│  StringBuilder Pool                     │
-│  ┌──────────┐ ┌──────────┐ ┌────────┐ │
-│  │ Cap:256  │ │ Cap:512  │ │Cap:1024│ │
-│  └──────────┘ └──────────┘ └────────┘ │
-└────────────────┬───────────────────────┘
-                 │ Get(capacity_hint)
-                 ▼
-           ┌───────────┐
-           │ Use & sb  │ sb.Clear() + Return
-           │ .Append() │────────────────────┐
-           └───────────┘                    │
-                 │ sb.ToString()            │
-                 ▼                          ▼
-            "result"                    Pool
-```
-
-### Implementation
-
-```csharp
-namespace WallstopStudios.UnityHelpers.Utils
-{
-    using System;
-    using System.Text;
-
-    public static class Buffers
-    {
-        private static readonly ObjectPool<StringBuilder> stringBuilderPool =
-            new ObjectPool<StringBuilder>(
-                initialCapacity: 4,
-                maxSize: 32,
-                resetAction: sb => sb.Clear()
-            );
-
-        public static class StringBuilder
-        {
-            /// <summary>
-            /// Get a pooled StringBuilder with optional capacity hint.
-            /// </summary>
-            public static PooledResource<System.Text.StringBuilder> Get(
-                out System.Text.StringBuilder sb,
-                int capacityHint = 256)
-            {
-                sb = stringBuilderPool.Rent();
-
-                // Ensure minimum capacity without shrinking
-                if (sb.Capacity < capacityHint)
-                {
-                    sb.Capacity = capacityHint;
-                }
-
-                return new PooledResource<System.Text.StringBuilder>(sb, ReturnToPool);
-            }
-
-            private static void ReturnToPool(System.Text.StringBuilder sb)
-            {
-                // Clear content but preserve capacity
-                sb.Clear();
-
-                // Optional: Trim oversized builders to prevent memory bloat
-                if (sb.Capacity > 8192)
-                {
-                    sb.Capacity = 256;
-                }
-
-                stringBuilderPool.Return(sb);
-            }
-        }
-
-        /// <summary>
-        /// Convenience method matching common API.
-        /// </summary>
-        public static PooledResource<System.Text.StringBuilder> GetStringBuilder(
-            int capacityHint,
-            out System.Text.StringBuilder sb)
-        {
-            return StringBuilder.Get(out sb, capacityHint);
-        }
-    }
-}
-```
-
-## Usage
-
-### Basic Usage
-
-```csharp
-public string BuildItemList(List<Item> items)
-{
-    using var lease = Buffers.StringBuilder.Get(out StringBuilder sb, items.Count * 20);
-
-    for (int i = 0; i < items.Count; i++)
-    {
-        sb.Append(items[i].Name);
-        if (i < items.Count - 1)
-        {
-            sb.Append(", ");
-        }
-    }
-
-    return sb.ToString();
-} // sb.Clear() + return to pool
-```
-
-### Formatting with Values
-
-```csharp
-public string FormatStats(Player player)
-{
-    using var lease = Buffers.StringBuilder.Get(out StringBuilder sb, 128);
-
-    sb.Append("HP: ").Append(player.Health).Append('/').Append(player.MaxHealth);
-    sb.AppendLine();
-    sb.Append("MP: ").Append(player.Mana).Append('/').Append(player.MaxMana);
-    sb.AppendLine();
-    sb.Append("Level: ").Append(player.Level);
-
-    return sb.ToString();
-}
-```
-
-### JSON-like Building
-
-```csharp
-public string ToJson(Dictionary<string, object> data)
-{
-    using var lease = Buffers.StringBuilder.Get(out StringBuilder sb, 512);
-
-    sb.Append('{');
-    bool first = true;
-
-    foreach (KeyValuePair<string, object> kvp in data)
-    {
-        if (!first) sb.Append(',');
-        first = false;
-
-        sb.Append('"').Append(kvp.Key).Append("\":");
-
-        if (kvp.Value is string str)
-        {
-            sb.Append('"').Append(str).Append('"');
-        }
-        else
-        {
-            sb.Append(kvp.Value);
-        }
-    }
-
-    sb.Append('}');
-    return sb.ToString();
-}
-```
-
-## Performance Notes
-
-- **Allocations**: Zero in steady state; only `ToString()` allocates (unavoidable)
-- **Capacity Hints**: Providing accurate hints avoids internal resizing
-- **Memory**: Pool auto-trims oversized builders (>8KB default)
-- **Timing**: O(1) pool operations
-
-### Benchmark Comparison
-
-| Approach             | 100 items | Allocations      |
-| -------------------- | --------- | ---------------- |
-| String +=            | 15.2ms    | 199 strings      |
-| New StringBuilder    | 0.8ms     | 1 StringBuilder  |
-| Pooled StringBuilder | 0.8ms     | 0 (steady state) |
-
-## Best Practices
-
-### Do
-
-- Estimate capacity: `items.Count * avgItemLength`
-- Use `Append()` chains for readability
-- Pool StringBuilders used in Update loops
-- Call `ToString()` only once at the end
-
-### Don't
-
-- Don't call `ToString()` multiple times (creates copies)
-- Don't store StringBuilder references beyond the using scope
-- Don't forget the capacity hint for large strings
-- Don't pool for one-time operations (allocation amortization not worth it)
-
-## Variations
-
-### Thread-Local StringBuilder
-
-For multithreaded code without locking:
-
-```csharp
-[ThreadStatic]
-private static StringBuilder threadLocalBuilder;
-
-public static StringBuilder GetThreadLocal()
-{
-    StringBuilder sb = threadLocalBuilder ?? (threadLocalBuilder = new StringBuilder(256));
-    sb.Clear();
-    return sb;
-}
-```
-
-## Related Patterns
-
-- [Collection Pooling](./collection-pooling.md) - General collection pooling
-- [GC-Free String Formatting](./gc-free-string-formatting.md) - Advanced string techniques

package/.llm/skills/performance/yield-instruction-pooling.md

@@ -1,347 +0,0 @@
----
-title: "WaitForSeconds and Yield Instruction Pooling"
-id: "yield-instruction-pooling"
-category: "performance"
-version: "1.0.0"
-created: "2026-01-21"
-updated: "2026-01-21"
-
-source:
-  repository: "wallstop/unity-helpers"
-  files:
-    - path: "Runtime/Utils/Buffers.cs"
-      lines: "148-467"
-  url: "https://github.com/wallstop/unity-helpers"
-
-tags:
-  - "performance"
-  - "unity"
-  - "coroutines"
-  - "pooling"
-  - "zero-alloc"
-  - "yield"
-
-complexity:
-  level: "basic"
-  reasoning: "Simple caching pattern with straightforward API"
-
-impact:
-  performance:
-    rating: "high"
-    details: "Eliminates per-coroutine allocations for common wait instructions"
-  maintainability:
-    rating: "high"
-    details: "Drop-in replacement for standard yield instructions"
-  testability:
-    rating: "high"
-    details: "Coroutine behavior unchanged; only allocation differs"
-
-prerequisites:
-  - "Understanding of Unity coroutines"
-  - "Knowledge of yield instructions"
-
-dependencies:
-  packages: []
-  skills: []
-
-applies_to:
-  languages:
-    - "C#"
-  frameworks:
-    - "Unity"
-  versions:
-    unity: ">=2021.3"
-
-aliases:
-  - "Cached WaitForSeconds"
-  - "Coroutine optimization"
-  - "Yield caching"
-
-related:
-  - "object-pooling"
-  - "collection-pooling"
-
-status: "stable"
----
-
-# WaitForSeconds and Yield Instruction Pooling
-
-> **One-line summary**: Cache and reuse Unity yield instructions like `WaitForSeconds` to eliminate per-coroutine allocations.
-
-## Overview
-
-Unity coroutines frequently use `yield return new WaitForSeconds(x)`, creating a new object each time. Since `WaitForSeconds` is reusable after completion, we can cache instances by duration to achieve zero-allocation coroutines.
-
-## Problem Statement
-
-```csharp
-// BAD: Allocates 20 bytes every call
-private IEnumerator SpawnEnemies()
-{
-    while (true)
-    {
-        SpawnEnemy();
-        yield return new WaitForSeconds(2f); // New allocation!
-    }
-}
-```
-
-With 100 coroutines at 1 yield/second = 2KB/second = 7.2MB/hour of garbage.
-
-## Solution
-
-### Core Concept
-
-```text
-┌─────────────────────────────────────────────────────────────────┐
-│                 WaitForSeconds Cache                             │
-├─────────────────────────────────────────────────────────────────┤
-│  Key (quantized seconds) │ Value (WaitForSeconds instance)      │
-│  ───────────────────────────────────────────────────────────    │
-│  0.0f                    │ WaitForSeconds(0.0f)                 │
-│  0.1f                    │ WaitForSeconds(0.1f)                 │
-│  0.5f                    │ WaitForSeconds(0.5f)                 │
-│  1.0f                    │ WaitForSeconds(1.0f)                 │
-│  2.0f                    │ WaitForSeconds(2.0f)                 │
-│  ...                     │ ...                                   │
-└─────────────────────────────────────────────────────────────────┘
-
-GetWaitForSeconds(1.5f) → Quantize to 1.5f → Return cached instance
-```
-
-### Implementation
-
-```csharp
-namespace WallstopStudios.UnityHelpers.Utils
-{
-    using System.Collections.Generic;
-    using UnityEngine;
-
-    public static partial class Buffers
-    {
-        /// <summary>
-        /// Quantization step for WaitForSeconds caching.
-        /// Smaller = more precision, larger cache.
-        /// </summary>
-        public static float WaitInstructionQuantizationStepSeconds { get; set; } = 0.05f;
-
-        private static readonly Dictionary<float, WaitForSeconds> waitForSecondsCache =
-            new Dictionary<float, WaitForSeconds>(64);
-
-        private static readonly Dictionary<float, WaitForSecondsRealtime> waitForSecondsRealtimeCache =
-            new Dictionary<float, WaitForSecondsRealtime>(32);
-
-        // Static singleton instances for common instructions
-        private static WaitForEndOfFrame waitForEndOfFrame;
-        private static WaitForFixedUpdate waitForFixedUpdate;
-
-        /// <summary>
-        /// Gets a cached WaitForEndOfFrame instance.
-        /// </summary>
-        public static WaitForEndOfFrame WaitForEndOfFrame =>
-            waitForEndOfFrame ?? (waitForEndOfFrame = new WaitForEndOfFrame());
-
-        /// <summary>
-        /// Gets a cached WaitForFixedUpdate instance.
-        /// </summary>
-        public static WaitForFixedUpdate WaitForFixedUpdate =>
-            waitForFixedUpdate ?? (waitForFixedUpdate = new WaitForFixedUpdate());
-
-        /// <summary>
-        /// Gets a cached WaitForSeconds for the given duration.
-        /// Duration is quantized to reduce cache entries.
-        /// </summary>
-        public static WaitForSeconds GetWaitForSeconds(float seconds)
-        {
-            float quantized = QuantizeTime(seconds);
-
-            if (!waitForSecondsCache.TryGetValue(quantized, out WaitForSeconds cached))
-            {
-                cached = new WaitForSeconds(quantized);
-                waitForSecondsCache[quantized] = cached;
-            }
-
-            return cached;
-        }
-
-        /// <summary>
-        /// Gets a cached WaitForSecondsRealtime for the given duration.
-        /// </summary>
-        public static WaitForSecondsRealtime GetWaitForSecondsRealtime(float seconds)
-        {
-            float quantized = QuantizeTime(seconds);
-
-            if (!waitForSecondsRealtimeCache.TryGetValue(quantized, out WaitForSecondsRealtime cached))
-            {
-                cached = new WaitForSecondsRealtime(quantized);
-                waitForSecondsRealtimeCache[quantized] = cached;
-            }
-
-            return cached;
-        }
-
-        /// <summary>
-        /// Try to get cached WaitForSeconds. Returns null if cache is at capacity.
-        /// Use this in memory-constrained scenarios.
-        /// </summary>
-        public static WaitForSeconds TryGetWaitForSecondsPooled(
-            float seconds,
-            int maxCacheSize = 100)
-        {
-            float quantized = QuantizeTime(seconds);
-
-            if (waitForSecondsCache.TryGetValue(quantized, out WaitForSeconds cached))
-            {
-                return cached;
-            }
-
-            if (waitForSecondsCache.Count >= maxCacheSize)
-            {
-                return null; // Caller should create new instance
-            }
-
-            cached = new WaitForSeconds(quantized);
-            waitForSecondsCache[quantized] = cached;
-            return cached;
-        }
-
-        private static float QuantizeTime(float seconds)
-        {
-            if (seconds <= 0f) return 0f;
-
-            float step = WaitInstructionQuantizationStepSeconds;
-            return Mathf.Round(seconds / step) * step;
-        }
-
-        /// <summary>
-        /// Clears all cached yield instructions.
-        /// Call when loading new scene if memory is tight.
-        /// </summary>
-        public static void ClearYieldCaches()
-        {
-            waitForSecondsCache.Clear();
-            waitForSecondsRealtimeCache.Clear();
-        }
-    }
-}
-```
-
-## Usage
-
-### Basic Coroutine
-
-```csharp
-private IEnumerator SpawnEnemies()
-{
-    while (true)
-    {
-        SpawnEnemy();
-        yield return Buffers.GetWaitForSeconds(2f); // Cached!
-    }
-}
-```
-
-### Common Yield Instructions
-
-```csharp
-private IEnumerator UpdateLoop()
-{
-    while (true)
-    {
-        // These are static singletons - always zero allocation
-        yield return Buffers.WaitForEndOfFrame;
-        UpdateUI();
-
-        yield return Buffers.WaitForFixedUpdate;
-        UpdatePhysics();
-
-        // Cached by duration
-        yield return Buffers.GetWaitForSeconds(0.5f);
-    }
-}
-```
-
-### Realtime Waits (Pause-Safe)
-
-```csharp
-private IEnumerator FadeOut()
-{
-    float elapsed = 0f;
-    float duration = 1f;
-
-    while (elapsed < duration)
-    {
-        elapsed += Time.unscaledDeltaTime;
-        SetAlpha(1f - (elapsed / duration));
-        yield return Buffers.GetWaitForSecondsRealtime(0.016f); // ~60fps
-    }
-}
-```
-
-### Memory-Constrained Fallback
-
-```csharp
-private IEnumerator DynamicDelay(float delay)
-{
-    WaitForSeconds wait = Buffers.TryGetWaitForSecondsPooled(delay, maxCacheSize: 50);
-
-    if (wait != null)
-    {
-        yield return wait;
-    }
-    else
-    {
-        // Cache full, create temporary (will be GC'd)
-        yield return new WaitForSeconds(delay);
-    }
-}
-```
-
-## Performance Notes
-
-- **Allocations**: Zero after initial cache population
-- **Cache Size**: ~20 bytes per cached duration
-- **Quantization**: 0.05s step = max 200 entries for 0-10s range
-- **Lookup**: O(1) dictionary access
-
-### Cache Growth Behavior
-
-| Duration Range | Quantization | Max Entries |
-| -------------- | ------------ | ----------- |
-| 0-1s           | 0.05s        | 20          |
-| 0-5s           | 0.05s        | 100         |
-| 0-10s          | 0.1s         | 100         |
-
-## Best Practices
-
-### Do
-
-- Use static singleton properties for `WaitForEndOfFrame`/`WaitForFixedUpdate`
-- Use `GetWaitForSeconds` for common durations
-- Call `ClearYieldCaches()` on scene transitions if memory is tight
-- Adjust `WaitInstructionQuantizationStepSeconds` based on precision needs
-
-### Don't
-
-- Don't create new `WaitForSeconds` in hot coroutines
-- Don't cache unique random durations (defeats purpose)
-- Don't use very small quantization steps (cache bloat)
-- Don't share `WaitForSecondsRealtime` across threads (not thread-safe)
-
-### Quantization Trade-offs
-
-```csharp
-// Precise (more cache entries)
-Buffers.WaitInstructionQuantizationStepSeconds = 0.01f;
-
-// Balanced (default)
-Buffers.WaitInstructionQuantizationStepSeconds = 0.05f;
-
-// Coarse (fewer entries, less precision)
-Buffers.WaitInstructionQuantizationStepSeconds = 0.25f;
-```
-
-## Related Patterns
-
-- [Object Pooling](./object-pooling.md) - General pooling pattern
-- [Collection Pooling](./collection-pooling.md) - Pooling with RAII