com.wallstop-studios.dxmessaging 3.0.1 → 3.1.0

package/Runtime/Core/InstanceId.cs

@@ -50,10 +50,34 @@ namespace DxMessaging.Core
 #if UNITY_2021_3_OR_NEWER
         private InstanceId(UnityEngine.Object unityObject)
         {
-            _id = unityObject.GetInstanceID();
+            _id = StableId(unityObject);
             Object = unityObject;
         }
 
+        /// <summary>
+        /// Returns the stable per-object integer identity used as the dispatch key.
+        /// Unity 6 is migrating object identity to the 64-bit <c>EntityId</c>:
+        /// <c>GetInstanceID()</c> is deprecated and becomes a compile error in Unity 6.5,
+        /// and successive raw accessors (the <c>EntityId</c>-to-<c>int</c> cast, then
+        /// <c>GetRawData()</c>) have each been deprecated in turn. On Unity 6.4+ this reads
+        /// the non-deprecated <c>EntityId.ToULong(...)</c> and keeps its low 32 bits --
+        /// exactly the integer the legacy <c>GetInstanceID()</c> returned (verified on 6.4
+        /// across GameObject/Component/ScriptableObject). Older Unity keeps
+        /// <c>GetInstanceID()</c> (valid, warning-only there, never the 6.5 error). The
+        /// 32-bit dispatch key is identical either way; only the (non-deprecated) source
+        /// differs. The gate is the host-verified 6.4 rather than 6.2 because the exact
+        /// accessor that is non-deprecated has shifted across Unity 6 minors.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        internal static int StableId(UnityEngine.Object unityObject)
+        {
+#if UNITY_6000_4_OR_NEWER
+            return unchecked((int)UnityEngine.EntityId.ToULong(unityObject.GetEntityId()));
+#else
+            return unityObject.GetInstanceID();
+#endif
+        }
+
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         /// <summary>
         /// Converts a <see cref="UnityEngine.GameObject"/> reference into an <see cref="InstanceId"/>.

package/Runtime/Core/Internal/DxUnsafe.cs

@@ -0,0 +1,60 @@
+namespace DxMessaging.Core.Internal
+{
+    using System.Runtime.CompilerServices;
+    // Qualified with global:: because this assembly also declares a DxMessaging.Unity
+    // namespace; an unqualified "using Unity.Collections..." would bind to
+    // DxMessaging.Unity.Collections and fail to resolve.
+    using global::Unity.Collections.LowLevel.Unsafe;
+
+    /// <summary>
+    /// Reinterpret-cast helpers used by the hot dispatch path. Each method wraps a Unity
+    /// <see cref="UnsafeUtility"/> intrinsic, which resolves in both the Editor and every
+    /// player build (Mono and IL2CPP, including the .NET Standard 2.0 profile) without an
+    /// external precompiled assembly.
+    /// </summary>
+    /// <remarks>
+    /// These are drop-in replacements for the corresponding
+    /// <c>System.Runtime.CompilerServices.Unsafe</c> members. That type is supplied by the
+    /// Editor but is absent from player builds, so referencing it compiled in the Editor yet
+    /// failed standalone IL2CPP compilation. <see cref="UnsafeUtility"/> ships inside
+    /// <c>UnityEngine.CoreModule</c> on every supported platform, so routing through it keeps
+    /// the zero-allocation reinterpret behavior while removing the unresolved dependency.
+    /// The wrapped intrinsics are pure IL (no internal-call transition), so this indirection
+    /// is free once inlined.
+    /// </remarks>
+    internal static class DxUnsafe
+    {
+        /// <summary>
+        /// Reinterprets a managed reference to <typeparamref name="TFrom"/> as a reference to
+        /// <typeparamref name="TTo"/> in place, without copying or boxing. Callers guarantee the
+        /// reinterpretation is valid for the concrete runtime layout.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        internal static ref TTo As<TFrom, TTo>(ref TFrom source)
+        {
+            return ref UnsafeUtility.As<TFrom, TTo>(ref source);
+        }
+
+        /// <summary>
+        /// Reinterprets a reference-typed instance as <typeparamref name="TTo"/> without a type
+        /// check. Callers guarantee the runtime type, mirroring the prior unchecked
+        /// <c>Unsafe.As&lt;T&gt;(object)</c> usage.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        internal static TTo As<TTo>(object value)
+            where TTo : class
+        {
+            return UnsafeUtility.As<object, TTo>(ref value);
+        }
+
+        /// <summary>
+        /// Returns the size in bytes of <typeparamref name="T"/>.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        internal static int SizeOf<T>()
+            where T : struct
+        {
+            return UnsafeUtility.SizeOf<T>();
+        }
+    }
+}

package/Runtime/Core/Internal/DxUnsafe.cs.meta

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

package/Runtime/Core/Internal/FlatDispatch.cs

@@ -0,0 +1,198 @@
+namespace DxMessaging.Core.Internal
+{
+    using System;
+    using System.Buffers;
+    using System.Collections.Generic;
+    using DxMessaging.Core;
+
+    /// <summary>
+    /// One fully-resolved dispatch entry for slots whose delegates do NOT
+    /// receive the routing context (untargeted handle/post, and the
+    /// context-keyed Default-variant targeted/broadcast slots, where the
+    /// target/source is the routing key rather than a delegate parameter):
+    /// the owning <see cref="MessageHandler"/> (for the single live
+    /// <c>active</c> check) plus the final invocable delegate, resolved at
+    /// snapshot-build time. Steady-state dispatch over an array of these is
+    /// a single field read, one branch, and a direct delegate invocation per
+    /// entry - no dispatch link, no generation guard, no per-priority
+    /// dictionary lookup, and no type test.
+    /// </summary>
+    /// <typeparam name="TMessage">Concrete message type of the dispatch slot.</typeparam>
+    internal readonly struct FlatDispatchEntry<TMessage>
+        where TMessage : IMessage
+    {
+        public FlatDispatchEntry(
+            MessageHandler handler,
+            MessageHandler.FastHandler<TMessage> invoker
+        )
+        {
+            this.handler = handler;
+            this.invoker = invoker;
+        }
+
+        public readonly MessageHandler handler;
+        public readonly MessageHandler.FastHandler<TMessage> invoker;
+    }
+
+    /// <summary>
+    /// One fully-resolved dispatch entry for the WithoutContext
+    /// targeted/broadcast slots, whose delegates DO receive the routing
+    /// context (target/source <see cref="InstanceId"/>) as a parameter.
+    /// Mirrors <see cref="FlatDispatchEntry{TMessage}"/> with the
+    /// context-carrying delegate shape.
+    /// </summary>
+    /// <typeparam name="TMessage">Concrete message type of the dispatch slot.</typeparam>
+    internal readonly struct ContextFlatDispatchEntry<TMessage>
+        where TMessage : IMessage
+    {
+        public ContextFlatDispatchEntry(
+            MessageHandler handler,
+            MessageHandler.FastHandlerWithContext<TMessage> invoker
+        )
+        {
+            this.handler = handler;
+            this.invoker = invoker;
+        }
+
+        public readonly MessageHandler handler;
+        public readonly MessageHandler.FastHandlerWithContext<TMessage> invoker;
+    }
+
+    /// <summary>
+    /// Non-generic erasure base so the non-generic
+    /// <c>MessageBus.DispatchSnapshot</c> can carry and release a typed flat
+    /// entry array without knowing the closed message type (or the entry
+    /// shape). The snapshot's pooled-release path calls <see cref="Release"/>
+    /// exactly once per snapshot teardown; the typed holder returns its array
+    /// to the per-closed-generic pool.
+    /// </summary>
+    internal abstract class FlatDispatchArray
+    {
+        internal abstract void Release();
+    }
+
+    /// <summary>
+    /// Shared pooled-holder implementation for flat dispatch arrays: a pooled
+    /// entry array (rented from <see cref="ArrayPool{T}"/>) plus a small
+    /// per-closed-generic holder stack so registration-churn rebuilds
+    /// allocate nothing in steady state. Concrete holders
+    /// (<see cref="FlatDispatch{TMessage}"/>,
+    /// <see cref="ContextFlatDispatch{TMessage}"/>) only pick the entry
+    /// shape; all lifecycle logic lives here so the pool/lock/cap/released
+    /// pattern exists exactly once.
+    /// </summary>
+    /// <remarks>
+    /// Lifecycle mirrors the snapshot that owns the holder: the array is
+    /// frozen for the duration of any emission that acquired it (mutations
+    /// mark the owning DispatchState dirty and are observed by the NEXT
+    /// emission's rebuild), and it is released back to the pool only through
+    /// <c>DispatchSnapshot.Release()</c>. The <c>_released</c> flag guards
+    /// the holder against double-release (which would seat the same holder
+    /// in the pool twice and corrupt later rents): DEBUG builds assert,
+    /// release builds no-op the second call.
+    /// </remarks>
+    /// <typeparam name="TEntry">Resolved entry struct stored in the array.</typeparam>
+    /// <typeparam name="THolder">Concrete holder type (CRTP, for typed pooling).</typeparam>
+    internal abstract class PooledFlatDispatch<TEntry, THolder> : FlatDispatchArray
+        where THolder : PooledFlatDispatch<TEntry, THolder>, new()
+    {
+        private static readonly ArrayPool<TEntry> EntryPool = ArrayPool<TEntry>.Shared;
+
+        // Cold-path pool (rebuild/teardown only); the lock is uncontended in
+        // practice but keeps the holder pool safe if multiple buses are ever
+        // driven from different threads.
+        private static readonly Stack<THolder> HolderPool = new();
+        private static readonly object HolderPoolLock = new();
+        private const int MaxRetainedHolders = 64;
+
+        internal TEntry[] entries = Array.Empty<TEntry>();
+        internal int count;
+
+        // True while the holder is parked in (or eligible for) the pool;
+        // false while it is owned by a live DispatchSnapshot. Guards the
+        // rent/release lifecycle against double-release and rent-of-live.
+        private bool _released = true;
+
+        internal static THolder Rent(int capacity)
+        {
+            THolder holder = null;
+            lock (HolderPoolLock)
+            {
+                if (0 < HolderPool.Count)
+                {
+                    holder = HolderPool.Pop();
+                }
+            }
+
+            holder ??= new THolder();
+            System.Diagnostics.Debug.Assert(
+                holder._released,
+                "PooledFlatDispatch.Rent returned a holder that is still owned by a live "
+                    + "snapshot; a Release() was skipped or the pool was corrupted."
+            );
+            holder._released = false;
+            holder.entries = 0 < capacity ? EntryPool.Rent(capacity) : Array.Empty<TEntry>();
+            holder.count = 0;
+            return holder;
+        }
+
+        internal sealed override void Release()
+        {
+            if (_released)
+            {
+                System.Diagnostics.Debug.Assert(
+                    false,
+                    "PooledFlatDispatch.Release called twice on the same holder; the owning "
+                        + "DispatchSnapshot must release its flat array exactly once."
+                );
+                return;
+            }
+
+            _released = true;
+            TEntry[] localEntries = entries;
+            int localCount = count;
+            entries = Array.Empty<TEntry>();
+            count = 0;
+            if (0 < localEntries.Length)
+            {
+                Array.Clear(localEntries, 0, localCount);
+                EntryPool.Return(localEntries);
+            }
+
+            lock (HolderPoolLock)
+            {
+                if (HolderPool.Count < MaxRetainedHolders)
+                {
+                    HolderPool.Push((THolder)this);
+                }
+            }
+        }
+    }
+
+    /// <summary>
+    /// Pooled flat array of resolved entries for one
+    /// (bus, message-type[, context], phase) dispatch snapshot whose
+    /// delegates take only the message: untargeted handle/post and the
+    /// context-keyed (Default variant) targeted/broadcast handle/post slots.
+    /// Built at snapshot-build time by walking the bus priority buckets
+    /// ascending, then each bucket's MessageHandlers in bus insertion order,
+    /// then each handler's fast entries followed by its default entries
+    /// (both in first-registration order), so a plain forward iteration
+    /// reproduces the documented dispatch order exactly.
+    /// </summary>
+    /// <typeparam name="TMessage">Concrete message type of the dispatch slot.</typeparam>
+    internal sealed class FlatDispatch<TMessage>
+        : PooledFlatDispatch<FlatDispatchEntry<TMessage>, FlatDispatch<TMessage>>
+        where TMessage : IMessage { }
+
+    /// <summary>
+    /// Pooled flat array of resolved entries for one (bus, message-type,
+    /// phase) dispatch snapshot of a WithoutContext targeted/broadcast slot,
+    /// whose delegates receive the routing <see cref="InstanceId"/> alongside
+    /// the message. Build order matches <see cref="FlatDispatch{TMessage}"/>.
+    /// </summary>
+    /// <typeparam name="TMessage">Concrete message type of the dispatch slot.</typeparam>
+    internal sealed class ContextFlatDispatch<TMessage>
+        : PooledFlatDispatch<ContextFlatDispatchEntry<TMessage>, ContextFlatDispatch<TMessage>>
+        where TMessage : IMessage { }
+}

package/Runtime/Core/Internal/FlatDispatch.cs.meta

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

package/Runtime/Core/Internal/TypedSlots.cs

@@ -28,10 +28,9 @@ namespace DxMessaging.Core.Internal
     /// surface picks up no new members from the interface retrofit.
     /// </para>
     /// <para>
-    /// Deliberately a thin, marker-style surface: only the six members that
+    /// Deliberately a thin, marker-style surface: only the five members that
     /// staged dispatch (<see cref="Version"/>, <see cref="LastSeenVersion"/>,
-    /// <see cref="LastSeenEmissionId"/>,
-    /// <see cref="PrefreezeInvocationCount"/>) and eviction
+    /// <see cref="LastSeenEmissionId"/>) and eviction
     /// (<see cref="IsEmpty"/>, <see cref="Reset"/>) require. The
     /// <c>entries</c> dictionary and <c>cache</c> list are NOT exposed
     /// because their generic shape is the very thing this interface erases;
@@ -67,15 +66,6 @@ namespace DxMessaging.Core.Internal
         /// </summary>
         long LastSeenEmissionId { get; set; }
 
-        /// <summary>
-        /// Number of invocations observed during the prefreeze window for
-        /// the most recent dispatch. Mirrors
-        /// <c>HandlerActionCache&lt;TDelegate&gt;.prefreezeInvocationCount</c>.
-        /// Read-only on this surface; the cache's own dispatchers maintain
-        /// the value.
-        /// </summary>
-        int PrefreezeInvocationCount { get; }
-
         /// <summary>
         /// True iff the cache currently retains zero entries. Cheap (single
         /// integer compare against <c>entries.Count</c>); used by the
@@ -87,7 +77,7 @@ namespace DxMessaging.Core.Internal
         /// <summary>
         /// Eviction-driven full clear. Empties the entries dictionary and
         /// the flat cache list, resets <see cref="LastSeenVersion"/> /
-        /// <see cref="LastSeenEmissionId"/> / <c>prefreezeInvocationCount</c>,
+        /// <see cref="LastSeenEmissionId"/>,
         /// and bumps <see cref="Version"/> as the LAST step so any captured
         /// dispatch closure that observed the prior version detects
         /// invalidation. Idempotent.
@@ -109,8 +99,8 @@ namespace DxMessaging.Core.Internal
         int MessageTypeIndex { get; }
 
         /// <summary>
-        /// True when the last sweep found no live typed slots or dispatch links
-        /// worth retaining and the owning <c>MessageCache</c> entry can be
+        /// True when the last sweep found no live typed slots worth
+        /// retaining and the owning <c>MessageCache</c> entry can be
         /// removed.
         /// </summary>
         bool MarkedForOuterRemoval { get; }
@@ -169,12 +159,6 @@ namespace DxMessaging.Core.Internal
     /// <c>_slots[<see cref="TypedSlotIndex.Length"/>]</c> array the
     /// storage owner.
     /// </para>
-    /// <para>
-    /// <see cref="TypedHandler{T}"/> owns a
-    /// <c>_dispatchLinks[<see cref="TypedDispatchLinkIndex.Length"/>]</c>
-    /// array as a plain <c>object[]</c> field. It is not a slot type; the
-    /// legacy named dispatch-link fields were removed.
-    /// </para>
     /// </remarks>
     /// <typeparam name="T">
     /// The strongly-typed message contract this slot's parent

package/Runtime/Core/MessageBus/IMessageBus.cs

@@ -109,23 +109,23 @@ namespace DxMessaging.Core.MessageBus
 
         internal static bool ShouldEnableDiagnostics()
         {
-            DiagnosticsTarget targets = GlobalDiagnosticsTargets;
+#if UNITY_2021_3_OR_NEWER
+            return ShouldEnableDiagnostics(GlobalDiagnosticsTargets, Application.isEditor);
+#else
+            return ShouldEnableDiagnostics(GlobalDiagnosticsTargets, isEditor: false);
+#endif
+        }
+
+        internal static bool ShouldEnableDiagnostics(DiagnosticsTarget targets, bool isEditor)
+        {
             if (targets == DiagnosticsTarget.Off)
             {
                 return false;
             }
 
-#if UNITY_2021_3_OR_NEWER
-            if (Application.isEditor)
-            {
-                return targets.HasFlagNoAlloc(DiagnosticsTarget.Editor)
-                    || targets.HasFlagNoAlloc(DiagnosticsTarget.Runtime);
-            }
-
-            return targets.HasFlagNoAlloc(DiagnosticsTarget.Editor);
-#else
-            return targets.HasFlagNoAlloc(DiagnosticsTarget.Runtime);
-#endif
+            return isEditor
+                ? targets.HasFlagNoAlloc(DiagnosticsTarget.Editor)
+                : targets.HasFlagNoAlloc(DiagnosticsTarget.Runtime);
         }
 
         /// <summary>

package/Runtime/Core/MessageBus/IMessageRegistrationBuilder.cs

@@ -13,6 +13,7 @@ namespace DxMessaging.Core.MessageBus
         /// <param name="options">Build configuration describing ownership, message bus preference, and lifecycle hooks.</param>
         /// <returns>Lease that exposes the constructed <see cref="MessageRegistrationToken"/>.</returns>
         /// <exception cref="ArgumentNullException"><paramref name="options"/> is <see langword="null"/>.</exception>
+        /// <exception cref="MessageRegistrationBuildException">ActivateOnBuild activation failed and automatic cleanup remains retryable.</exception>
         MessageRegistrationLease Build(MessageRegistrationBuildOptions options);
     }
 }

package/Runtime/Core/MessageBus/Internal/BusSlots.cs

@@ -4,6 +4,7 @@ namespace DxMessaging.Core.MessageBus.Internal
     using System.Diagnostics;
     using System.Runtime.CompilerServices;
     using DxMessaging.Core;
+    using DxMessaging.Core.Internal;
     using DxMessaging.Core.Pooling;
 
     /// <summary>
@@ -277,7 +278,7 @@ namespace DxMessaging.Core.MessageBus.Internal
     /// <c>Dictionary&lt;InstanceId, object&gt;</c> -- generic-erased to share a
     /// single pool across every message-type instantiation. Each value is a
     /// <see cref="BusSinkSlot"/>, accessed via
-    /// <see cref="Unsafe.As{T}(object)"/>; the class is sealed and only inserted
+    /// <see cref="DxUnsafe.As{T}(object)"/>; the class is sealed and only inserted
     /// from this type's own methods, so the cast cannot encounter a foreign
     /// runtime type. <c>DEBUG</c> builds verify the invariant at every
     /// cast site.
@@ -378,7 +379,7 @@ namespace DxMessaging.Core.MessageBus.Internal
                 return false;
             }
             DebugAssertSlot(boxed);
-            slot = Unsafe.As<BusSinkSlot>(boxed);
+            slot = DxUnsafe.As<BusSinkSlot>(boxed);
             return true;
         }
 
@@ -403,7 +404,7 @@ namespace DxMessaging.Core.MessageBus.Internal
             if (map.TryGetValue(context, out object boxed))
             {
                 DebugAssertSlot(boxed);
-                return Unsafe.As<BusSinkSlot>(boxed);
+                return DxUnsafe.As<BusSinkSlot>(boxed);
             }
             BusSinkSlot slot = new BusSinkSlot();
             map[context] = slot;
@@ -463,7 +464,7 @@ namespace DxMessaging.Core.MessageBus.Internal
                         continue;
                     }
                     DebugAssertSlot(boxed);
-                    Unsafe.As<BusSinkSlot>(boxed).Clear();
+                    DxUnsafe.As<BusSinkSlot>(boxed).Clear();
                 }
                 map.Clear();
             }
@@ -494,7 +495,7 @@ namespace DxMessaging.Core.MessageBus.Internal
                         continue;
                     }
                     DebugAssertSlot(boxed);
-                    Unsafe.As<BusSinkSlot>(boxed).Reset();
+                    DxUnsafe.As<BusSinkSlot>(boxed).Reset();
                 }
                 // Pool's onRecycled callback clears the dictionary before re-use.
                 DxPools.InstanceIdDicts.Return(map);
@@ -513,7 +514,7 @@ namespace DxMessaging.Core.MessageBus.Internal
             Debug.Assert(
                 boxed is BusSinkSlot,
                 "BusContextSlot.byContext must only contain BusSinkSlot values; "
-                    + "Unsafe.As<BusSinkSlot> would otherwise produce undefined behavior."
+                    + "DxUnsafe.As<BusSinkSlot> would otherwise produce undefined behavior."
             );
         }
     }