com.wallstop-studios.dxmessaging 2.1.1 → 2.1.3

package/Runtime/Core/MessageHandler.cs

@@ -345,12 +345,14 @@ namespace DxMessaging.Core
         )
             where TMessage : IMessage;
 
+        private static readonly object GlobalResetLock = new object();
+
         /// <summary>
         /// Global message bus used when no explicit bus is provided.
         /// </summary>
         private static IMessageBus _globalMessageBus;
 
-        private static readonly MessageBus.MessageBus _defaultGlobalMessageBus = new();
+        private static MessageBus.MessageBus _defaultGlobalMessageBus = new MessageBus.MessageBus();
 
         /// <summary>
         /// Gets the process-wide <see cref="IMessageBus"/> used when no explicit bus is supplied.
@@ -363,16 +365,17 @@ namespace DxMessaging.Core
         public static IMessageBus MessageBus => _globalMessageBus;
 
         /// <summary>
-        /// Gets the original global <see cref="IMessageBus"/> instance created during static initialisation.
+        /// Gets the baseline global <see cref="IMessageBus"/> instance used when no custom bus is configured.
         /// </summary>
         /// <remarks>
-        /// This reference never changes even when <see cref="SetGlobalMessageBus(IMessageBus)"/> is invoked.
+        /// The instance is recreated when <see cref="DxMessagingStaticState.Reset"/> runs so that domain-reload-disabled
+        /// environments can obtain a clean slate.
         /// </remarks>
         public static IMessageBus InitialGlobalMessageBus => _defaultGlobalMessageBus;
 
         static MessageHandler()
         {
-            _globalMessageBus = _defaultGlobalMessageBus;
+            ResetStatics();
         }
 
         /// <summary>
@@ -417,11 +420,14 @@ namespace DxMessaging.Core
         /// Restores the global <see cref="MessageBus.MessageBus"/> to the built-in default instance.
         /// </summary>
         /// <remarks>
-        /// The default instance is created during static initialisation and reused across resets to minimise allocations.
+        /// The default instance is recreated by <see cref="ResetStatics"/> when the static state reset utility runs.
         /// </remarks>
         public static void ResetGlobalMessageBus()
         {
-            _globalMessageBus = _defaultGlobalMessageBus;
+            lock (GlobalResetLock)
+            {
+                _globalMessageBus = _defaultGlobalMessageBus;
+            }
         }
 
         /// <summary>
@@ -434,6 +440,21 @@ namespace DxMessaging.Core
             return new GlobalMessageBusScope(messageBus);
         }
 
+        /// <summary>
+        /// Recreates the built-in global <see cref="MessageBus.MessageBus"/> and assigns it as the active global bus.
+        /// </summary>
+        /// <remarks>
+        /// Invoked by <see cref="DxMessagingStaticState.Reset"/> to provide a clean slate when domain reloads are disabled.
+        /// </remarks>
+        internal static void ResetStatics()
+        {
+            lock (GlobalResetLock)
+            {
+                _defaultGlobalMessageBus.ResetState();
+                _globalMessageBus = _defaultGlobalMessageBus;
+            }
+        }
+
         /// <summary>
         /// Represents a disposable override scope for the global message bus.
         /// </summary>
@@ -462,6 +483,9 @@ namespace DxMessaging.Core
                 }
             }
 
+            /// <summary>
+            /// Restores the previously active global message bus when the scope ends.
+            /// </summary>
             public void Dispose()
             {
                 if (_disposed)
@@ -502,7 +526,7 @@ namespace DxMessaging.Core
         /// <note>
         /// Ideally, this would be something like a Dictionary[T, Handler[T]], but that can't be done with C#s type system.
         /// </note>
-        private readonly List<MessageCache<object>> _handlersByTypeByMessageBus;
+        internal readonly List<MessageCache<object>> _handlersByTypeByMessageBus;
         private IMessageBus _defaultMessageBus;
 
         /// <summary>
@@ -514,6 +538,14 @@ namespace DxMessaging.Core
         /// </remarks>
         public IMessageBus DefaultMessageBus => _defaultMessageBus ?? MessageBus;
 
+        /// <summary>
+        /// Initializes a message handler bound to the specified owner and optional default bus.
+        /// </summary>
+        /// <param name="owner">Identity of the object that owns this handler.</param>
+        /// <param name="defaultMessageBus">
+        /// Preferred bus to use when registrations do not specify one. Falls back to
+        /// <see cref="MessageBus"/> if omitted.
+        /// </param>
         public MessageHandler(InstanceId owner, IMessageBus defaultMessageBus = null)
         {
             this.owner = owner;
@@ -1832,11 +1864,21 @@ namespace DxMessaging.Core
             return messageBus.RegisterTargetedInterceptor(interceptor, priority);
         }
 
+        /// <summary>
+        /// Checks equality against another object.
+        /// </summary>
+        /// <param name="obj">Object to compare.</param>
+        /// <returns><c>true</c> when <paramref name="obj"/> is a <see cref="MessageHandler"/> with the same owner.</returns>
         public override bool Equals(object obj)
         {
             return Equals(obj as MessageHandler);
         }
 
+        /// <summary>
+        /// Checks equality against another handler instance.
+        /// </summary>
+        /// <param name="other">Handler to compare.</param>
+        /// <returns><c>true</c> when both handlers share the same <see cref="owner"/>.</returns>
         public bool Equals(MessageHandler other)
         {
             if (other == null)
@@ -1852,11 +1894,20 @@ namespace DxMessaging.Core
             return owner.Equals(other.owner);
         }
 
+        /// <summary>
+        /// Produces a hash code based on the owning instance.
+        /// </summary>
+        /// <returns>Hash code derived from <see cref="owner"/>.</returns>
         public override int GetHashCode()
         {
             return owner.GetHashCode();
         }
 
+        /// <summary>
+        /// Compares this handler with another handler for ordering.
+        /// </summary>
+        /// <param name="other">Handler to compare.</param>
+        /// <returns>Relative ordering based on <see cref="owner"/>.</returns>
         public int CompareTo(MessageHandler other)
         {
             if (other == null)
@@ -1867,11 +1918,22 @@ namespace DxMessaging.Core
             return owner.CompareTo(other.owner);
         }
 
+        /// <summary>
+        /// Compares this handler with an arbitrary object.
+        /// </summary>
+        /// <param name="obj">Object to compare.</param>
+        /// <returns>
+        /// Relative ordering when <paramref name="obj"/> is a <see cref="MessageHandler"/>; otherwise <c>-1</c>.
+        /// </returns>
         public int CompareTo(object obj)
         {
             return CompareTo(obj as MessageHandler);
         }
 
+        /// <summary>
+        /// Returns a human-readable representation containing the owner identifier.
+        /// </summary>
+        /// <returns>String describing the handler.</returns>
         public override string ToString()
         {
             return new { OwnerId = owner }.ToString();
@@ -1934,10 +1996,42 @@ namespace DxMessaging.Core
             return false;
         }
 
+        internal int GetUntargetedPostProcessingPrefreezeCount<T>(
+            IMessageBus messageBus,
+            int priority
+        )
+            where T : IMessage
+        {
+            if (
+                !GetHandlerForType(messageBus, out TypedHandler<T> handler)
+                || handler._untargetedPostProcessingFastHandlers == null
+            )
+            {
+                return 0;
+            }
+
+            if (
+                handler._untargetedPostProcessingFastHandlers.TryGetValue(
+                    priority,
+                    out HandlerActionCache<FastHandler<T>> cache
+                )
+            )
+            {
+                return cache.prefreezeInvocationCount;
+            }
+
+            return 0;
+        }
+
         private sealed class HandlerActionCache<T>
         {
             internal readonly struct Entry
             {
+                /// <summary>
+                /// Initializes an entry used to track handler invocation counts.
+                /// </summary>
+                /// <param name="handler">Handler delegate being tracked.</param>
+                /// <param name="count">Number of times the handler has been cached.</param>
                 public Entry(T handler, int count)
                 {
                     this.handler = handler;
@@ -2318,6 +2412,12 @@ namespace DxMessaging.Core
                 }
             }
 
+            /// <summary>
+            /// Runs untargeted post-processing handlers for the supplied message.
+            /// </summary>
+            /// <param name="message">Message being processed.</param>
+            /// <param name="priority">Priority bucket currently executing.</param>
+            /// <param name="emissionId">Emission identifier used to cache handler stacks.</param>
             public void HandleUntargetedPostProcessing(ref T message, int priority, long emissionId)
             {
                 RunFastHandlers(
@@ -2329,6 +2429,13 @@ namespace DxMessaging.Core
                 RunHandlers(_untargetedPostProcessingHandlers, ref message, priority, emissionId);
             }
 
+            /// <summary>
+            /// Runs targeted post-processing handlers for the supplied message and recipient.
+            /// </summary>
+            /// <param name="target">Recipient of the message.</param>
+            /// <param name="message">Message being processed.</param>
+            /// <param name="priority">Priority bucket currently executing.</param>
+            /// <param name="emissionId">Emission identifier used to cache handler stacks.</param>
             public void HandleTargetedPostProcessing(
                 ref InstanceId target,
                 ref T message,
@@ -2352,6 +2459,13 @@ namespace DxMessaging.Core
                 );
             }
 
+            /// <summary>
+            /// Runs targeted post-processing handlers that do not require a <see cref="InstanceId"/> target binding.
+            /// </summary>
+            /// <param name="target">Recipient of the message.</param>
+            /// <param name="message">Message being processed.</param>
+            /// <param name="priority">Priority bucket currently executing.</param>
+            /// <param name="emissionId">Emission identifier used to cache handler stacks.</param>
             public void HandleTargetedWithoutTargetingPostProcessing(
                 ref InstanceId target,
                 ref T message,
@@ -2375,6 +2489,13 @@ namespace DxMessaging.Core
                 );
             }
 
+            /// <summary>
+            /// Runs broadcast post-processing handlers that expect a concrete source identifier.
+            /// </summary>
+            /// <param name="source">Origin of the message.</param>
+            /// <param name="message">Message being processed.</param>
+            /// <param name="priority">Priority bucket currently executing.</param>
+            /// <param name="emissionId">Emission identifier used to cache handler stacks.</param>
             public void HandleSourcedBroadcastPostProcessing(
                 ref InstanceId source,
                 ref T message,
@@ -2398,6 +2519,13 @@ namespace DxMessaging.Core
                 );
             }
 
+            /// <summary>
+            /// Runs broadcast post-processing handlers that do not rely on a specific source identifier.
+            /// </summary>
+            /// <param name="source">Origin of the message.</param>
+            /// <param name="message">Message being processed.</param>
+            /// <param name="priority">Priority bucket currently executing.</param>
+            /// <param name="emissionId">Emission identifier used to cache handler stacks.</param>
             public void HandleBroadcastWithoutSourcePostProcessing(
                 ref InstanceId source,
                 ref T message,
@@ -3673,7 +3801,12 @@ namespace DxMessaging.Core
                     {
                         List<TU> list = actionCache.cache;
                         list.Clear();
-                        foreach (var kvp in actionCache.entries)
+                        foreach (
+                            KeyValuePair<
+                                TU,
+                                HandlerActionCache<TU>.Entry
+                            > kvp in actionCache.entries
+                        )
                         {
                             list.Add(kvp.Value.handler);
                         }

package/Runtime/Core/MessageRegistrationHandle.cs

@@ -19,6 +19,21 @@ namespace DxMessaging.Core
         private readonly long _id;
         private readonly int _hashCode;
 
+        internal static long GetCurrentIdSeed()
+        {
+            return Interlocked.Read(ref StaticIdCount);
+        }
+
+        internal static void SetIdSeed(long value)
+        {
+            _ = Interlocked.Exchange(ref StaticIdCount, value);
+        }
+
+        internal static void ResetIdSeed()
+        {
+            SetIdSeed(0);
+        }
+
         /// <summary>
         /// Creates a new unique handle.
         /// </summary>
@@ -49,6 +64,12 @@ namespace DxMessaging.Core
             return !left.Equals(right);
         }
 
+        /// <summary>
+        /// Determines whether the left handle sorts after the right handle.
+        /// </summary>
+        /// <param name="left">Left-hand handle.</param>
+        /// <param name="right">Right-hand handle.</param>
+        /// <returns><c>true</c> when <paramref name="left"/> sorts after <paramref name="right"/>.</returns>
         public static bool operator >(
             MessageRegistrationHandle left,
             MessageRegistrationHandle right
@@ -57,6 +78,12 @@ namespace DxMessaging.Core
             return left.CompareTo(right) > 0;
         }
 
+        /// <summary>
+        /// Determines whether the left handle sorts before the right handle.
+        /// </summary>
+        /// <param name="left">Left-hand handle.</param>
+        /// <param name="right">Right-hand handle.</param>
+        /// <returns><c>true</c> when <paramref name="left"/> sorts before <paramref name="right"/>.</returns>
         public static bool operator <(
             MessageRegistrationHandle left,
             MessageRegistrationHandle right
@@ -81,11 +108,23 @@ namespace DxMessaging.Core
             return left.CompareTo(right) >= 0;
         }
 
+        /// <summary>
+        /// Compares this handle with another handle for ordering.
+        /// </summary>
+        /// <param name="other">Other handle to compare with.</param>
+        /// <returns>Relative ordering as defined by <see cref="IComparable{T}.CompareTo(T)"/>.</returns>
         public int CompareTo(MessageRegistrationHandle other)
         {
             return _id.CompareTo(other._id);
         }
 
+        /// <summary>
+        /// Compares this handle with an arbitrary object.
+        /// </summary>
+        /// <param name="obj">Object to compare with.</param>
+        /// <returns>
+        /// Relative ordering when <paramref name="obj"/> is a <see cref="MessageRegistrationHandle"/>; otherwise <c>-1</c>.
+        /// </returns>
         public int CompareTo(object obj)
         {
             if (obj is MessageRegistrationHandle handle)
@@ -96,21 +135,41 @@ namespace DxMessaging.Core
             return -1;
         }
 
+        /// <summary>
+        /// Checks equality against another object.
+        /// </summary>
+        /// <param name="other">Object to compare.</param>
+        /// <returns>
+        /// <c>true</c> when <paramref name="other"/> is a <see cref="MessageRegistrationHandle"/> representing the same registration.
+        /// </returns>
         public override bool Equals(object other)
         {
             return other is MessageRegistrationHandle handle && Equals(handle);
         }
 
+        /// <summary>
+        /// Checks equality against another handle.
+        /// </summary>
+        /// <param name="other">Handle to compare.</param>
+        /// <returns><c>true</c> when both handles represent the same registration.</returns>
         public bool Equals(MessageRegistrationHandle other)
         {
             return _id == other._id;
         }
 
+        /// <summary>
+        /// Produces a hash code suitable for dictionary or set lookups.
+        /// </summary>
+        /// <returns>Hash code derived from the internal identifier.</returns>
         public override int GetHashCode()
         {
             return _hashCode;
         }
 
+        /// <summary>
+        /// Returns a string representation of the handle, including the underlying identifier.
+        /// </summary>
+        /// <returns>Human-readable representation of the handle.</returns>
         public override string ToString()
         {
             return new { Id = _id }.ToString();

package/Runtime/Core/MessageRegistrationToken.cs

@@ -39,7 +39,7 @@ namespace DxMessaging.Core
     /// }
     /// </code>
     /// </example>
-    public sealed class MessageRegistrationToken
+    public sealed class MessageRegistrationToken : IDisposable
     {
         /// <summary>
         /// Whether the token is currently enabled (registrations are active).
@@ -71,7 +71,7 @@ namespace DxMessaging.Core
 
         private IMessageBus _messageBus;
         private bool _enabled;
-        private bool _diagnosticMode = IMessageBus.GlobalDiagnosticsMode;
+        private bool _diagnosticMode = IMessageBus.ShouldEnableDiagnostics();
 
         private MessageRegistrationToken(MessageHandler messageHandler, IMessageBus messageBus)
         {
@@ -166,7 +166,7 @@ namespace DxMessaging.Core
             );
         }
 
-#if UNITY_2017_1_OR_NEWER
+#if UNITY_2021_3_OR_NEWER
         /// <summary>
         /// Stages a registration to accept targeted messages of type <typeparamref name="T"/> directed at the given GameObject.
         /// </summary>
@@ -1024,7 +1024,7 @@ namespace DxMessaging.Core
             );
         }
 
-#if UNITY_2017_1_OR_NEWER
+#if UNITY_2021_3_OR_NEWER
         /// <summary>
         /// Stages a registration to accept broadcast messages of type <typeparamref name="T"/> from a given source.
         /// </summary>
@@ -1995,6 +1995,11 @@ namespace DxMessaging.Core
             private readonly MessageRegistrationHandle _handle;
             private bool _valid;
 
+            /// <summary>
+            /// Creates a disposable wrapper that removes a registration when disposed.
+            /// </summary>
+            /// <param name="token">Token that owns the registration.</param>
+            /// <param name="handle">Handle to remove when disposed.</param>
             public RegistrationDisposable(
                 MessageRegistrationToken token,
                 MessageRegistrationHandle handle
@@ -2005,6 +2010,9 @@ namespace DxMessaging.Core
                 _valid = true;
             }
 
+            /// <summary>
+            /// Removes the wrapped registration the first time it is invoked.
+            /// </summary>
             public void Dispose()
             {
                 // Best-effort idempotence; AsDisposable instances are short-lived and immutable
@@ -2035,5 +2043,13 @@ namespace DxMessaging.Core
 
             return new MessageRegistrationToken(messageHandler, messageBus);
         }
+
+        /// <summary>
+        /// Removes all staged registrations and releases references to the handler.
+        /// </summary>
+        public void Dispose()
+        {
+            UnregisterAll();
+        }
     }
 }

package/Runtime/Core/Messages/ReflexiveMessage.cs

@@ -17,10 +17,29 @@ namespace DxMessaging.Core.Messages
     public enum ReflexiveSendMode
     {
         [Obsolete("Please use a valid Send Mode")]
+        /// <summary>
+        /// Legacy sentinel indicating no traversal; not supported.
+        /// </summary>
         None = 0,
+
+        /// <summary>
+        /// Invoke matching methods only on the immediate GameObject.
+        /// </summary>
         Flat = 1 << 0,
+
+        /// <summary>
+        /// Traverse into child GameObjects when invoking methods.
+        /// </summary>
         Downwards = 1 << 1,
+
+        /// <summary>
+        /// Traverse up the parent chain when invoking methods.
+        /// </summary>
         Upwards = 1 << 2,
+
+        /// <summary>
+        /// Skip disabled components during traversal.
+        /// </summary>
         OnlyIncludeActive = 1 << 3,
     }
 
@@ -34,6 +53,11 @@ namespace DxMessaging.Core.Messages
 
         private readonly int _hashCode;
 
+        /// <summary>
+        /// Creates a lookup key for a reflected method signature.
+        /// </summary>
+        /// <param name="methodName">Name of the method.</param>
+        /// <param name="parameterTypes">Ordered parameter list expected by the method.</param>
         public MethodSignatureKey(string methodName, Type[] parameterTypes)
             : this()
         {
@@ -54,16 +78,30 @@ namespace DxMessaging.Core.Messages
             return hashCode;
         }
 
+        /// <summary>
+        /// Gets a stable hash code for the method signature.
+        /// </summary>
+        /// <returns>Hash code derived from the name and parameter types.</returns>
         public override int GetHashCode()
         {
             return _hashCode;
         }
 
+        /// <summary>
+        /// Checks equality against an arbitrary object.
+        /// </summary>
+        /// <param name="obj">Object to compare.</param>
+        /// <returns><c>true</c> when <paramref name="obj"/> represents the same signature.</returns>
         public override bool Equals(object obj)
         {
             return obj is MethodSignatureKey other && Equals(other);
         }
 
+        /// <summary>
+        /// Checks equality against another method signature key.
+        /// </summary>
+        /// <param name="other">Signature key to compare with.</param>
+        /// <returns><c>true</c> when both keys describe the same method.</returns>
         public bool Equals(MethodSignatureKey other)
         {
             if (

package/Runtime/Core/MessagingDebug.cs

@@ -3,13 +3,28 @@ namespace DxMessaging.Core
     using System;
 
     /// <summary>
-    /// Severity of the log message
+    /// Severity of the log message.
     /// </summary>
     public enum LogLevel
     {
+        /// <summary>
+        /// Verbose diagnostic information useful while developing or debugging.
+        /// </summary>
         Debug = 0,
+
+        /// <summary>
+        /// Informational messages that describe normal operation.
+        /// </summary>
         Info = 1,
+
+        /// <summary>
+        /// Non-fatal issues that should be investigated.
+        /// </summary>
         Warn = 2,
+
+        /// <summary>
+        /// Errors indicating messaging failed or data may be lost.
+        /// </summary>
         Error = 3,
     }
 

package/Runtime/Unity/CurrentGlobalMessageBusProvider.cs

@@ -1,3 +1,4 @@
+#if UNITY_2021_3_OR_NEWER
 namespace DxMessaging.Unity
 {
     using DxMessaging.Core;
@@ -23,9 +24,14 @@ namespace DxMessaging.Unity
     )]
     public sealed class CurrentGlobalMessageBusProvider : ScriptableMessageBusProvider
     {
+        /// <summary>
+        /// Resolves the message bus currently set as the global bus via <see cref="MessageHandler.SetGlobalMessageBus(IMessageBus)"/>.
+        /// </summary>
+        /// <returns>The active global <see cref="IMessageBus"/> instance.</returns>
         public override IMessageBus Resolve()
         {
             return MessageHandler.MessageBus;
         }
     }
 }
+#endif

package/Runtime/Unity/DxMessagingRuntimeInitializer.cs

@@ -0,0 +1,19 @@
+#if UNITY_2021_3_OR_NEWER
+namespace DxMessaging.Unity
+{
+    using Core;
+    using UnityEngine;
+
+    /// <summary>
+    /// Unity-specific hook that resets DxMessaging static state when domain reloads are skipped.
+    /// </summary>
+    internal static class DxMessagingRuntimeInitializer
+    {
+        [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
+        private static void ResetStatics()
+        {
+            DxMessagingStaticState.Reset();
+        }
+    }
+}
+#endif

package/Runtime/Unity/DxMessagingRuntimeInitializer.cs.meta

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

package/Runtime/Unity/InitialGlobalMessageBusProvider.cs

@@ -1,3 +1,4 @@
+#if UNITY_2021_3_OR_NEWER
 namespace DxMessaging.Unity
 {
     using DxMessaging.Core;
@@ -30,9 +31,14 @@ namespace DxMessaging.Unity
     )]
     public sealed class InitialGlobalMessageBusProvider : ScriptableMessageBusProvider
     {
+        /// <summary>
+        /// Resolves the message bus captured during static initialization before any runtime overrides occur.
+        /// </summary>
+        /// <returns>The initial global <see cref="IMessageBus"/> instance.</returns>
         public override IMessageBus Resolve()
         {
             return MessageHandler.InitialGlobalMessageBus;
         }
     }
 }
+#endif