com.wallstop-studios.dxmessaging 2.1.3 → 2.1.5

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

@@ -0,0 +1,313 @@
+---
+title: "Collection Pooling with RAII Pattern"
+id: "collection-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: "1-500"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "memory"
+  - "allocation"
+  - "pooling"
+  - "zero-alloc"
+  - "collections"
+  - "raii"
+  - "disposable"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of IDisposable and RAII patterns, but usage is straightforward"
+
+impact:
+  performance:
+    rating: "high"
+    details: "Eliminates per-operation allocations for Lists, HashSets, Stacks, Queues, and StringBuilders"
+  maintainability:
+    rating: "high"
+    details: "using statements ensure proper cleanup; pattern is self-documenting"
+  testability:
+    rating: "high"
+    details: "Pools can be tested in isolation; behavior tests unaffected by pooling"
+
+prerequisites:
+  - "Understanding of IDisposable"
+  - "Knowledge of using statements"
+
+dependencies:
+  packages: []
+  skills:
+    - "object-pooling"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+    dotnet: ">=netstandard2.1"
+
+aliases:
+  - "Buffers pattern"
+  - "PooledResource"
+  - "Collection reuse"
+
+related:
+  - "object-pooling"
+  - "stringbuilder-pooling"
+  - "array-pooling"
+
+status: "stable"
+---
+
+# Collection Pooling with RAII Pattern
+
+> **One-line summary**: Use PooledResource<T> with `using` statements to automatically rent and return collections, achieving zero-allocation collection usage in hot paths.
+
+## Overview
+
+Collection pooling provides reusable instances of common collection types (List, HashSet, Stack, Queue, StringBuilder) with automatic cleanup. The RAII (Resource Acquisition Is Initialization) pattern via `IDisposable` ensures collections are:
+
+1. **Rented** when entering scope
+1. **Cleared** when exiting scope (removing stale data)
+1. **Returned** to the pool automatically
+
+This eliminates the most common source of per-frame allocations in Unity games.
+
+## Problem Statement
+
+```csharp
+// BAD: Allocates a new List every call
+public void ProcessEnemies(Vector3 playerPos)
+{
+    List<Enemy> nearby = new List<Enemy>(); // 40+ byte allocation
+    foreach (Enemy e in allEnemies)
+    {
+        if (Vector3.Distance(e.Position, playerPos) < 10f)
+        {
+            nearby.Add(e);
+        }
+    }
+    // nearby becomes garbage after this method
+}
+```
+
+Called 60 times per second = 2,400 List allocations per minute = GC spikes.
+
+## Solution
+
+### Core Concept
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  using (PooledResource<List<T>> lease = Pool.Get(out list)) │
+│  {                                                           │
+│      // Use list...                                          │
+│  } // <-- Dispose() called: list.Clear(), return to pool    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Implementation
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Utils
+{
+    using System;
+    using System.Collections.Generic;
+
+    /// <summary>
+    /// RAII wrapper that returns a pooled object on Dispose.
+    /// </summary>
+    public readonly struct PooledResource<T> : IDisposable where T : class
+    {
+        private readonly T value;
+        private readonly Action<T> returnAction;
+
+        public T Value => value;
+
+        internal PooledResource(T value, Action<T> returnAction)
+        {
+            this.value = value;
+            this.returnAction = returnAction;
+        }
+
+        public void Dispose()
+        {
+            returnAction?.Invoke(value);
+        }
+    }
+
+    /// <summary>
+    /// Generic collection pool with typed accessors.
+    /// </summary>
+    public static class Buffers<T>
+    {
+        private static readonly ObjectPool<List<T>> listPool =
+            new ObjectPool<List<T>>(
+                initialCapacity: 8,
+                resetAction: list => list.Clear()
+            );
+
+        private static readonly ObjectPool<HashSet<T>> hashSetPool =
+            new ObjectPool<HashSet<T>>(
+                initialCapacity: 4,
+                resetAction: set => set.Clear()
+            );
+
+        private static readonly ObjectPool<Stack<T>> stackPool =
+            new ObjectPool<Stack<T>>(
+                initialCapacity: 4,
+                resetAction: stack => stack.Clear()
+            );
+
+        private static readonly ObjectPool<Queue<T>> queuePool =
+            new ObjectPool<Queue<T>>(
+                initialCapacity: 4,
+                resetAction: queue => queue.Clear()
+            );
+
+        public static class List
+        {
+            public static PooledResource<List<T>> Get(out List<T> list)
+            {
+                list = listPool.Rent();
+                return new PooledResource<List<T>>(list, l =>
+                {
+                    l.Clear();
+                    listPool.Return(l);
+                });
+            }
+        }
+
+        public static class HashSet
+        {
+            public static PooledResource<HashSet<T>> Get(out HashSet<T> set)
+            {
+                set = hashSetPool.Rent();
+                return new PooledResource<HashSet<T>>(set, s =>
+                {
+                    s.Clear();
+                    hashSetPool.Return(s);
+                });
+            }
+        }
+
+        public static class Stack
+        {
+            public static PooledResource<Stack<T>> Get(out Stack<T> stack)
+            {
+                stack = stackPool.Rent();
+                return new PooledResource<Stack<T>>(stack, s =>
+                {
+                    s.Clear();
+                    stackPool.Return(s);
+                });
+            }
+        }
+
+        public static class Queue
+        {
+            public static PooledResource<Queue<T>> Get(out Queue<T> queue)
+            {
+                queue = queuePool.Rent();
+                return new PooledResource<Queue<T>>(queue, q =>
+                {
+                    q.Clear();
+                    queuePool.Return(q);
+                });
+            }
+        }
+    }
+}
+```
+
+## Usage
+
+### Basic List Pooling
+
+```csharp
+public void ProcessEnemies(Vector3 playerPos)
+{
+    using PooledResource<List<Enemy>> lease = Buffers<Enemy>.List.Get(out List<Enemy> nearby);
+
+    foreach (Enemy e in allEnemies)
+    {
+        if (Vector3.Distance(e.Position, playerPos) < 10f)
+        {
+            nearby.Add(e);
+        }
+    }
+
+    foreach (Enemy e in nearby)
+    {
+        e.ReactToPlayer();
+    }
+    // lease.Dispose() called automatically: nearby.Clear() + return to pool
+}
+```
+
+### Nested Collection Usage
+
+```csharp
+public void BuildGraph()
+{
+    using var nodesLease = Buffers<Node>.List.Get(out List<Node> nodes);
+    using var visitedLease = Buffers<Node>.HashSet.Get(out HashSet<Node> visited);
+    using var pendingLease = Buffers<Node>.Queue.Get(out Queue<Node> pending);
+
+    pending.Enqueue(rootNode);
+
+    while (pending.Count > 0)
+    {
+        Node current = pending.Dequeue();
+        if (visited.Add(current))
+        {
+            nodes.Add(current);
+            foreach (Node child in current.Children)
+            {
+                pending.Enqueue(child);
+            }
+        }
+    }
+
+    ProcessNodes(nodes);
+} // All three collections cleared and returned
+```
+
+## Performance Notes
+
+- **Allocations**: Zero in steady state; one-time pool warm-up
+- **Timing**: O(1) rent/return; pool operations are constant time
+- **Memory**: Pool grows to high-water mark, then stabilizes
+- **Thread Safety**: Consider per-thread pools for multithreaded code
+
+## Best Practices
+
+### Do
+
+- Use `using var` for concise syntax (C# 8+)
+- Pre-size collections if you know approximate size: `list.Capacity = expectedCount`
+- Pool collections used in Update/FixedUpdate/LateUpdate
+- Clear collections before returning (handled automatically)
+
+### Don't
+
+- Don't store references to pooled collections beyond the using scope
+- Don't return collections manually if using PooledResource
+- Don't pool collections with finalizers or native resources
+- Don't share PooledResource across threads
+
+## Related Patterns
+
+- [Object Pooling](./object-pooling.md) - Base pooling pattern
+- [StringBuilder Pooling](./stringbuilder-pooling.md) - Specialized string building
+- [Array Pooling](./array-pooling.md) - Fixed-size buffer pooling

package/.llm/skills/performance/object-pooling-anti-patterns.md

@@ -0,0 +1,144 @@
+---
+title: "Object Pooling Anti-Patterns"
+id: "object-pooling-anti-patterns"
+category: "performance"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "Runtime/"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "memory"
+  - "allocation"
+  - "pooling"
+  - "messaging"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Expands on object pooling details and trade-offs"
+
+impact:
+  performance:
+    rating: "high"
+    details: "Pooled objects reduce GC pressure in hot paths"
+  maintainability:
+    rating: "medium"
+    details: "Requires disciplined lifecycle management"
+  testability:
+    rating: "medium"
+    details: "Pooling patterns need explicit tests for reuse"
+
+prerequisites:
+  - "Understanding of object pooling"
+
+dependencies:
+  packages: []
+  skills:
+    - "object-pooling"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+    dotnet: ">=netstandard2.0"
+
+aliases:
+  - "Object pooling details"
+
+related:
+  - "object-pooling"
+
+status: "stable"
+---
+
+# Object Pooling Anti-Patterns
+
+> **One-line summary**: Common mistakes to avoid when using pooled objects.
+
+## Overview
+
+This skill documents common mistakes that break pooling safety or correctness.
+
+## Solution
+
+Avoid the anti-patterns below and follow the safer alternatives.
+
+## Anti-Patterns
+
+### Don't Hold References to Pooled Objects
+
+```csharp
+public class BadHandler
+{
+    private DamageMessage lastDamage; // WRONG: Holding pooled object
+
+    public void OnDamage(DamageMessage message)
+    {
+        lastDamage = message; // This reference becomes invalid after handler returns!
+    }
+}
+```
+
+**Why it's wrong**: The pooled object will be reset and reused. Your reference will contain stale or corrupted data.
+
+**Fix**: Copy the data you need:
+
+```csharp
+public class GoodHandler
+{
+    private int lastDamageAmount;
+    private InstanceId lastDamageSource;
+
+    public void OnDamage(DamageMessage message)
+    {
+        lastDamageAmount = message.Damage;
+        lastDamageSource = message.Source;
+    }
+}
+```
+
+### Don't Forget to Return Objects
+
+```csharp
+public void ProcessDamage()
+{
+    DamageMessage message = DamageMessage.Rent();
+    message.Damage = 10;
+
+    if (SomeCondition())
+    {
+        return; // WRONG: message leaked, becomes garbage
+    }
+
+    messageBus.Emit(message);
+    message.Dispose();
+}
+```
+
+**Fix**: Use try/finally or `using`:
+
+```csharp
+public void ProcessDamage()
+{
+    using (DamageMessage message = DamageMessage.Rent())
+    {
+        message.Damage = 10;
+
+        if (SomeCondition())
+        {
+            return; // Safe: Dispose called automatically
+        }
+
+        messageBus.Emit(message);
+    }
+}
+```

package/.llm/skills/performance/object-pooling-usage-examples.md

@@ -0,0 +1,114 @@
+---
+title: "Object Pooling Usage Examples"
+id: "object-pooling-usage-examples"
+category: "performance"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "Runtime/"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "memory"
+  - "allocation"
+  - "pooling"
+  - "messaging"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Expands on object pooling details and trade-offs"
+
+impact:
+  performance:
+    rating: "high"
+    details: "Pooled objects reduce GC pressure in hot paths"
+  maintainability:
+    rating: "medium"
+    details: "Requires disciplined lifecycle management"
+  testability:
+    rating: "medium"
+    details: "Pooling patterns need explicit tests for reuse"
+
+prerequisites:
+  - "Understanding of object pooling"
+
+dependencies:
+  packages: []
+  skills:
+    - "object-pooling"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+    dotnet: ">=netstandard2.0"
+
+aliases:
+  - "Object pooling details"
+
+related:
+  - "object-pooling"
+
+status: "stable"
+---
+
+# Object Pooling Usage Examples
+
+> **One-line summary**: Applied object pooling scenarios for high-frequency messaging.
+
+## Overview
+
+This skill provides applied object pooling examples for high-frequency messaging.
+
+## Solution
+
+Use the examples below as starting points for your own pools.
+
+## Usage Examples
+
+### Example 1: High-Frequency Combat Events
+
+```csharp
+public sealed class CombatSystem
+{
+    private readonly MessageBus messageBus;
+
+    public void ProcessAttack(InstanceId attacker, InstanceId target, int baseDamage)
+    {
+        // Rent from pool instead of allocating
+        DamageMessage message = DamageMessage.Rent();
+        message.Damage = CalculateDamage(baseDamage);
+        message.Source = attacker;
+
+        // Emit to all handlers
+        messageBus.Emit(target, message);
+
+        // Return to pool (or use 'using' statement)
+        message.Dispose();
+    }
+}
+```
+
+### Example 2: Using Statement for Automatic Return
+
+```csharp
+public void BroadcastAreaDamage(Vector3 center, float radius, int damage)
+{
+    using (AreaDamageMessage message = AreaDamageMessage.Rent())
+    {
+        message.Center = center;
+        message.Radius = radius;
+        message.Damage = damage;
+
+        messageBus.Broadcast(message);
+    } // Automatically returned to pool here
+}
+```

package/.llm/skills/performance/object-pooling-variations.md

@@ -0,0 +1,147 @@
+---
+title: "Object Pooling Variations"
+id: "object-pooling-variations"
+category: "performance"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "Runtime/"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "memory"
+  - "allocation"
+  - "pooling"
+  - "messaging"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Expands on object pooling details and trade-offs"
+
+impact:
+  performance:
+    rating: "high"
+    details: "Pooled objects reduce GC pressure in hot paths"
+  maintainability:
+    rating: "medium"
+    details: "Requires disciplined lifecycle management"
+  testability:
+    rating: "medium"
+    details: "Pooling patterns need explicit tests for reuse"
+
+prerequisites:
+  - "Understanding of object pooling"
+
+dependencies:
+  packages: []
+  skills:
+    - "object-pooling"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+    dotnet: ">=netstandard2.0"
+
+aliases:
+  - "Object pooling details"
+
+related:
+  - "object-pooling"
+
+status: "stable"
+---
+
+# Object Pooling Variations
+
+> **One-line summary**: Variations on object pooling for messaging and structs.
+
+## Overview
+
+This skill compares variations on pooled message and struct-based approaches.
+
+## Solution
+
+Choose the variant that matches allocation goals and API constraints.
+
+## Variations
+
+### Variation A: Pooled Message Base Class
+
+Create a base class that handles pool return automatically:
+
+```csharp
+public abstract class PooledMessage<TSelf> : IMessage, IDisposable
+    where TSelf : PooledMessage<TSelf>, new()
+{
+    private static readonly ObjectPool<TSelf> Pool = new ObjectPool<TSelf>(
+        initialCapacity: 32,
+        resetAction: m => m.Reset()
+    );
+
+    private bool isRented;
+
+    public static TSelf Rent()
+    {
+        TSelf instance = Pool.Rent();
+        instance.isRented = true;
+        return instance;
+    }
+
+    public void Dispose()
+    {
+        if (isRented)
+        {
+            isRented = false;
+            Pool.Return((TSelf)this);
+        }
+    }
+
+    /// <summary>
+    /// Override to clear instance-specific state.
+    /// </summary>
+    protected abstract void Reset();
+}
+
+// Usage
+public sealed class DamageMessage : PooledMessage<DamageMessage>
+{
+    public int Damage { get; set; }
+    public InstanceId Source { get; set; }
+
+    protected override void Reset()
+    {
+        Damage = 0;
+        Source = default;
+    }
+}
+```
+
+### Variation B: Struct-Based Zero-Alloc
+
+For maximum performance, use structs to avoid even pool overhead:
+
+```csharp
+public readonly struct DamageEvent : IMessage
+{
+    public readonly int Damage;
+    public readonly InstanceId Source;
+
+    public DamageEvent(int damage, InstanceId source)
+    {
+        Damage = damage;
+        Source = source;
+    }
+}
+
+// Emit by value - no allocation at all
+messageBus.Emit(new DamageEvent(10, attackerId));
+```