com.wallstop-studios.dxmessaging 2.2.0 → 3.1.0

package/Runtime/Core/Messages/ITargetedMessage.cs.meta

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: 5b82bbdd13cb3654aafba14e0c21ca52
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 5b82bbdd13cb3654aafba14e0c21ca52
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Core/Messages/IUntargetedMessage.cs.meta

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: 0a0789976ef004e4c926d5f25bd92e50
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 0a0789976ef004e4c926d5f25bd92e50
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Core/Messages/ReflexiveMessage.cs.meta

@@ -1,3 +1,11 @@
-fileFormatVersion: 2
-guid: f9a83f6bf3c0487f9e5cff498dbb6932
-timeCreated: 1745161955
+fileFormatVersion: 2
+guid: f9a83f6bf3c0487f9e5cff498dbb6932
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Runtime/Core/Messages/SourcedStringMessage.cs.meta

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: f5b6176a6924a364dbc509e1db5b30f4
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: f5b6176a6924a364dbc509e1db5b30f4
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Core/Messages/StringMessage.cs.meta

@@ -1,3 +1,11 @@
-fileFormatVersion: 2
-guid: cf8206ca4c8449a8b8e112ad25554f1f
-timeCreated: 1745161457
+fileFormatVersion: 2
+guid: cf8206ca4c8449a8b8e112ad25554f1f
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Runtime/Core/Messages.meta

@@ -1,8 +1,8 @@
-fileFormatVersion: 2
-guid: eb7aa358315732945a9f45ad92904b2f
-folderAsset: yes
-DefaultImporter:
-  externalObjects: {}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: eb7aa358315732945a9f45ad92904b2f
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Core/MessagingDebug.cs.meta

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: 95f160b63321b69489108cdf413b55d2
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 95f160b63321b69489108cdf413b55d2
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Core/Pooling/CollectionPool.cs

@@ -0,0 +1,266 @@
+namespace DxMessaging.Core.Pooling
+{
+    using System;
+    using System.Collections.Generic;
+
+    /// <summary>
+    /// Single-threaded object pool with bounded capacity and either LRU or LIFO
+    /// recycle order. Used by <see cref="DxPools"/> to recycle the dictionaries,
+    /// lists, sets, and stacks that DxMessaging slots rent and return on slot
+    /// reset. Not thread-safe by design -- the entire dispatch path is single-
+    /// threaded.
+    /// </summary>
+    /// <remarks>
+    /// Adapted from https://github.com/wallstop/unity-helpers/blob/de22dcd22fd98d4fe8c7aa8e70814496698681f7/Runtime/Utils/Buffers.cs
+    /// (single-threaded portion only -- the unity-helpers version supports
+    /// thread-static caches we do not need here).
+    /// </remarks>
+    internal sealed class CollectionPool<T>
+        where T : class, new()
+    {
+        private readonly Func<T> _factory;
+        private readonly Action<T> _onRecycled; // called once when a returned entry is accepted into the pool
+        private readonly Action<T> _onEvicted; // called when an entry is dropped (cap overflow or trim)
+        private bool _useLru;
+        private int _maxRetained;
+
+        // LRU state -- Queue<T> is FIFO with O(1) Enqueue/Dequeue (amortized)
+        // and avoids the per-node allocation that LinkedList incurs.
+        private readonly Queue<T> _lruQueue;
+        private readonly HashSet<T> _lruMembership;
+
+        // LIFO state
+        private readonly Stack<T> _stack;
+        private readonly HashSet<T> _stackMembership;
+
+        private readonly int _ownerThreadId = Environment.CurrentManagedThreadId;
+
+        private long _hits;
+        private long _misses;
+        private long _evictions;
+
+        public CollectionPool(
+            int maxRetained,
+            bool useLru,
+            Func<T> factory,
+            Action<T> onRecycled = null,
+            Action<T> onEvicted = null
+        )
+        {
+            if (maxRetained < 0)
+            {
+                throw new ArgumentOutOfRangeException(nameof(maxRetained));
+            }
+            _maxRetained = maxRetained;
+            _useLru = useLru;
+            _factory = factory ?? throw new ArgumentNullException(nameof(factory));
+            _onRecycled = onRecycled;
+            _onEvicted = onEvicted;
+            int initialCapacity = Math.Min(maxRetained, 32);
+            _lruQueue = new Queue<T>(initialCapacity);
+            _lruMembership = new HashSet<T>();
+            _stack = new Stack<T>(initialCapacity);
+            _stackMembership = new HashSet<T>();
+        }
+
+        /// <summary>Current cached count.</summary>
+        public int Count => _useLru ? _lruQueue.Count : _stack.Count;
+
+        /// <summary>Whether this pool evicts oldest returned entries first.</summary>
+        public bool UseLru
+        {
+            get => _useLru;
+            set
+            {
+                AssertOwnerThread();
+                if (_useLru == value)
+                {
+                    return;
+                }
+                if (value)
+                {
+                    ConvertStackToLru();
+                }
+                else
+                {
+                    ConvertLruToStack();
+                }
+                _useLru = value;
+            }
+        }
+
+        /// <summary>Soft cap on retained entries. Mutating this may evict.</summary>
+        public int MaxRetained
+        {
+            get => _maxRetained;
+            set
+            {
+                AssertOwnerThread();
+                if (value < 0)
+                {
+                    throw new ArgumentOutOfRangeException(nameof(value));
+                }
+                _maxRetained = value;
+                EvictDownTo(value);
+            }
+        }
+
+        public T Rent()
+        {
+            AssertOwnerThread();
+            if (_useLru)
+            {
+                if (_lruQueue.Count > 0)
+                {
+                    T pooled = _lruQueue.Dequeue();
+                    _lruMembership.Remove(pooled);
+                    _hits++;
+                    return pooled;
+                }
+            }
+            else if (_stack.Count > 0)
+            {
+                T pooled = _stack.Pop();
+                _stackMembership.Remove(pooled);
+                _hits++;
+                return pooled;
+            }
+            _misses++;
+            T fresh = _factory();
+            if (fresh == null)
+            {
+                throw new InvalidOperationException("CollectionPool factory returned null.");
+            }
+            return fresh;
+        }
+
+        public void Return(T value)
+        {
+            AssertOwnerThread();
+            if (value == null)
+            {
+                return;
+            }
+            if (_maxRetained == 0)
+            {
+                _evictions++;
+                _onEvicted?.Invoke(value);
+                return;
+            }
+            if (_useLru)
+            {
+                if (_lruMembership.Contains(value))
+                {
+                    return; // already pooled; ignore double-return
+                }
+                if (_lruQueue.Count >= _maxRetained)
+                {
+                    T head = _lruQueue.Dequeue();
+                    _lruMembership.Remove(head);
+                    _evictions++;
+                    _onEvicted?.Invoke(head);
+                }
+                _onRecycled?.Invoke(value);
+                _lruQueue.Enqueue(value);
+                _lruMembership.Add(value);
+            }
+            else
+            {
+                if (_stackMembership.Contains(value))
+                {
+                    return; // already pooled; ignore double-return
+                }
+                if (_stack.Count >= _maxRetained)
+                {
+                    _evictions++;
+                    _onEvicted?.Invoke(value);
+                    return;
+                }
+                _onRecycled?.Invoke(value);
+                _stack.Push(value);
+                _stackMembership.Add(value);
+            }
+        }
+
+        /// <summary>Trim the pool to <paramref name="targetSize"/>. Returns count evicted.</summary>
+        public int Trim(int targetSize)
+        {
+            AssertOwnerThread();
+            if (targetSize < 0)
+            {
+                targetSize = 0;
+            }
+            return EvictDownTo(targetSize);
+        }
+
+        public CollectionPoolDiagnostics Snapshot()
+        {
+            return new CollectionPoolDiagnostics(Count, _hits, _misses, _evictions);
+        }
+
+        private int EvictDownTo(int targetSize)
+        {
+            int evicted = 0;
+            if (_useLru)
+            {
+                while (_lruQueue.Count > targetSize)
+                {
+                    T head = _lruQueue.Dequeue();
+                    _lruMembership.Remove(head);
+                    _evictions++;
+                    evicted++;
+                    _onEvicted?.Invoke(head);
+                }
+            }
+            else
+            {
+                while (_stack.Count > targetSize)
+                {
+                    T item = _stack.Pop();
+                    _stackMembership.Remove(item);
+                    _evictions++;
+                    evicted++;
+                    _onEvicted?.Invoke(item);
+                }
+            }
+            return evicted;
+        }
+
+        private void ConvertLruToStack()
+        {
+            while (_lruQueue.Count > 0)
+            {
+                T item = _lruQueue.Dequeue();
+                _lruMembership.Remove(item);
+                _stack.Push(item);
+                _stackMembership.Add(item);
+            }
+        }
+
+        private void ConvertStackToLru()
+        {
+            T[] items = _stack.ToArray();
+            _stack.Clear();
+            _stackMembership.Clear();
+            for (int index = items.Length - 1; index >= 0; index--)
+            {
+                T item = items[index];
+                _lruQueue.Enqueue(item);
+                _lruMembership.Add(item);
+            }
+        }
+
+        [System.Diagnostics.Conditional("DEBUG")]
+        private void AssertOwnerThread()
+        {
+            if (Environment.CurrentManagedThreadId != _ownerThreadId)
+            {
+                throw new InvalidOperationException(
+                    "CollectionPool<"
+                        + typeof(T).Name
+                        + "> is single-threaded; accessed from foreign thread."
+                );
+            }
+        }
+    }
+}

package/Runtime/Core/Pooling/CollectionPool.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 61e4386511c8d9d20ab1c8be9cf95805
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Runtime/Core/Pooling/CollectionPoolDiagnostics.cs

@@ -0,0 +1,30 @@
+namespace DxMessaging.Core.Pooling
+{
+    /// <summary>
+    /// Snapshot of a single pool's lifetime counters and current cached count.
+    /// All values are point-in-time; reading them does not reset the underlying
+    /// counters. Useful for leak-watcher style assertions and for debug overlays.
+    /// </summary>
+    internal readonly struct CollectionPoolDiagnostics
+    {
+        /// <summary>Number of entries currently retained by the pool.</summary>
+        public readonly int Cached;
+
+        /// <summary>Lifetime count of <c>Rent</c> calls that returned a pooled entry.</summary>
+        public readonly long Hits;
+
+        /// <summary>Lifetime count of <c>Rent</c> calls that allocated a fresh entry.</summary>
+        public readonly long Misses;
+
+        /// <summary>Lifetime count of pooled entries dropped due to cap or LRU eviction.</summary>
+        public readonly long Evictions;
+
+        internal CollectionPoolDiagnostics(int cached, long hits, long misses, long evictions)
+        {
+            Cached = cached;
+            Hits = hits;
+            Misses = misses;
+            Evictions = evictions;
+        }
+    }
+}

package/Runtime/Core/Pooling/CollectionPoolDiagnostics.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 852381a5e8ddb842edb761718afc1f9f
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Runtime/Core/Pooling/DxPools.cs

@@ -0,0 +1,157 @@
+namespace DxMessaging.Core.Pooling
+{
+    using System.Collections.Generic;
+    using DxMessaging.Core.Internal;
+#if UNITY_2021_3_OR_NEWER
+    using Configuration;
+#endif
+
+    /// <summary>
+    /// Static, single-threaded pool registry shared by the bus and handler
+    /// subsystems. Instantiated lazily on first use; reconfigured by
+    /// <see cref="Configure"/> when the runtime settings asset changes.
+    /// </summary>
+    /// <remarks>
+    /// Each pool returns the per-entry recycle action that clears the entry
+    /// before re-use, so callers do not need to remember to <c>Clear()</c>
+    /// before <c>Return</c>. <c>OnEvicted</c> currently does nothing -- entries
+    /// are dropped on cap overflow and the GC reclaims them.
+    /// </remarks>
+    internal static class DxPools
+    {
+        // Mirrors DxMessagingRuntimeSettings.DefaultBufferMaxDistinctEntries; updated by Configure().
+        // Kept as a local constant so DxPools' field initializers don't depend on Unity types.
+        private const int DefaultMaxRetained = 512;
+
+        internal static readonly CollectionPool<Dictionary<InstanceId, object>> InstanceIdDicts =
+            new(
+                maxRetained: DefaultMaxRetained,
+                useLru: true,
+                factory: () => new Dictionary<InstanceId, object>(),
+                onRecycled: dict => dict.Clear()
+            );
+
+        internal static readonly CollectionPool<List<InstanceId>> InstanceIdLists = new(
+            maxRetained: DefaultMaxRetained,
+            useLru: true,
+            factory: () => new List<InstanceId>(),
+            onRecycled: list => list.Clear()
+        );
+
+        internal static readonly CollectionPool<HashSet<InstanceId>> InstanceIdSets = new(
+            maxRetained: DefaultMaxRetained,
+            useLru: true,
+            factory: () => new HashSet<InstanceId>(),
+            onRecycled: set => set.Clear()
+        );
+
+        internal static readonly CollectionPool<List<object>> ObjectLists = new(
+            maxRetained: DefaultMaxRetained,
+            useLru: true,
+            factory: () => new List<object>(),
+            onRecycled: list => list.Clear()
+        );
+
+        internal static readonly CollectionPool<Stack<object>> ObjectStacks = new(
+            maxRetained: DefaultMaxRetained,
+            useLru: true,
+            factory: () => new Stack<object>(),
+            onRecycled: stack => stack.Clear()
+        );
+
+        internal static readonly CollectionPool<HashSet<int>> IntSets = new(
+            maxRetained: DefaultMaxRetained,
+            useLru: true,
+            factory: () => new HashSet<int>(),
+            onRecycled: set => set.Clear()
+        );
+
+        internal static readonly CollectionPool<
+            Dictionary<InstanceId, Dictionary<int, IHandlerActionCache>>
+        > TypedHandlerContextDicts = new(
+            maxRetained: DefaultMaxRetained,
+            useLru: true,
+            factory: () => new Dictionary<InstanceId, Dictionary<int, IHandlerActionCache>>(),
+            onRecycled: dict => dict.Clear()
+        );
+
+        internal static readonly CollectionPool<
+            Dictionary<int, IHandlerActionCache>
+        > TypedHandlerPriorityDicts = new(
+            maxRetained: DefaultMaxRetained,
+            useLru: true,
+            factory: () => new Dictionary<int, IHandlerActionCache>(),
+            onRecycled: dict => dict.Clear()
+        );
+
+        /// <summary>
+        /// Trim every pool. <paramref name="force"/> drains pools to zero;
+        /// otherwise each pool is trimmed to its current cap (a no-op unless the
+        /// cap was lowered). Returns total evicted count.
+        /// </summary>
+        internal static int TrimAll(bool force)
+        {
+            int evicted = 0;
+            evicted += InstanceIdDicts.Trim(force ? 0 : InstanceIdDicts.MaxRetained);
+            evicted += InstanceIdLists.Trim(force ? 0 : InstanceIdLists.MaxRetained);
+            evicted += InstanceIdSets.Trim(force ? 0 : InstanceIdSets.MaxRetained);
+            evicted += ObjectLists.Trim(force ? 0 : ObjectLists.MaxRetained);
+            evicted += ObjectStacks.Trim(force ? 0 : ObjectStacks.MaxRetained);
+            evicted += IntSets.Trim(force ? 0 : IntSets.MaxRetained);
+            evicted += TypedHandlerContextDicts.Trim(
+                force ? 0 : TypedHandlerContextDicts.MaxRetained
+            );
+            evicted += TypedHandlerPriorityDicts.Trim(
+                force ? 0 : TypedHandlerPriorityDicts.MaxRetained
+            );
+            return evicted;
+        }
+
+#if UNITY_2021_3_OR_NEWER
+        /// <summary>
+        /// Re-apply caps from the supplied settings. Lowering a cap immediately
+        /// trims; raising a cap takes effect on subsequent returns.
+        /// </summary>
+        internal static void Configure(DxMessagingRuntimeSettings settings)
+        {
+            if (settings == null)
+            {
+                throw new System.ArgumentNullException(nameof(settings));
+            }
+            int cap = settings.BufferMaxDistinctEntries;
+            bool useLru = settings.BufferUseLruEviction;
+            InstanceIdDicts.UseLru = useLru;
+            InstanceIdLists.UseLru = useLru;
+            InstanceIdSets.UseLru = useLru;
+            ObjectLists.UseLru = useLru;
+            ObjectStacks.UseLru = useLru;
+            IntSets.UseLru = useLru;
+            TypedHandlerContextDicts.UseLru = useLru;
+            TypedHandlerPriorityDicts.UseLru = useLru;
+            InstanceIdDicts.MaxRetained = cap;
+            InstanceIdLists.MaxRetained = cap;
+            InstanceIdSets.MaxRetained = cap;
+            ObjectLists.MaxRetained = cap;
+            ObjectStacks.MaxRetained = cap;
+            IntSets.MaxRetained = cap;
+            TypedHandlerContextDicts.MaxRetained = cap;
+            TypedHandlerPriorityDicts.MaxRetained = cap;
+        }
+#endif
+
+        /// <summary>Aggregate snapshot of every pool's diagnostics.</summary>
+        internal static PoolDiagnosticsSnapshot DescribeAll()
+        {
+            return new PoolDiagnosticsSnapshot(
+                InstanceIdDicts.Snapshot(),
+                InstanceIdLists.Snapshot(),
+                InstanceIdSets.Snapshot(),
+                ObjectLists.Snapshot(),
+                ObjectStacks.Snapshot(),
+                IntSets.Snapshot(),
+                TypedHandlerContextDicts.Snapshot(),
+                TypedHandlerPriorityDicts.Snapshot()
+            );
+        }
+    }
+}

package/Runtime/Core/Pooling/DxPools.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: c15b462050f33ab6fd3c588a3cec8943
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant: