com.wallstop-studios.dxmessaging 2.1.2 → 2.1.4

package/Runtime/Core/MessageBus/MessageRegistrationBuilder.cs

@@ -99,6 +99,13 @@ namespace DxMessaging.Core.MessageBus
     /// </remarks>
     public readonly struct MessageRegistrationLifecycle
     {
+        /// <summary>
+        /// Creates a lifecycle definition with the supplied callbacks.
+        /// </summary>
+        /// <param name="onBuild">Invoked immediately after the lease is constructed.</param>
+        /// <param name="onActivate">Invoked when the lease becomes active.</param>
+        /// <param name="onDeactivate">Invoked when the lease transitions from active to inactive.</param>
+        /// <param name="onDispose">Invoked during lease disposal.</param>
         public MessageRegistrationLifecycle(
             Action<MessageRegistrationToken> onBuild,
             Action<MessageRegistrationToken> onActivate,
@@ -201,6 +208,9 @@ namespace DxMessaging.Core.MessageBus
             _isActive = true;
         }
 
+        /// <summary>
+        /// Deactivates the lease, unregistering staged handlers and invoking lifecycle hooks.
+        /// </summary>
         public void Deactivate()
         {
             if (_disposed || !_isActive)
@@ -218,6 +228,9 @@ namespace DxMessaging.Core.MessageBus
             _isActive = false;
         }
 
+        /// <summary>
+        /// Disposes the lease, unregistering handlers and executing lifecycle callbacks once.
+        /// </summary>
         public void Dispose()
         {
             if (_disposed)
@@ -259,11 +272,33 @@ namespace DxMessaging.Core.MessageBus
         private readonly IMessageBusProvider _messageBusProvider;
         private static int _syntheticOwnerCounter;
 
+        internal static int GetSyntheticOwnerCounter()
+        {
+            return Volatile.Read(ref _syntheticOwnerCounter);
+        }
+
+        internal static void SetSyntheticOwnerCounter(int value)
+        {
+            _ = Interlocked.Exchange(ref _syntheticOwnerCounter, value);
+        }
+
+        internal static void ResetSyntheticOwnerCounter()
+        {
+            SetSyntheticOwnerCounter(0);
+        }
+
+        /// <summary>
+        /// Initializes a builder that resolves buses from global state.
+        /// </summary>
         public MessageRegistrationBuilder()
         {
             _messageBusProvider = null;
         }
 
+        /// <summary>
+        /// Initializes a builder that uses a custom bus provider.
+        /// </summary>
+        /// <param name="messageBusProvider">Provider used to resolve message buses for new leases.</param>
         public MessageRegistrationBuilder(IMessageBusProvider messageBusProvider)
         {
             _messageBusProvider = messageBusProvider;
@@ -370,11 +405,20 @@ namespace DxMessaging.Core.MessageBus
     {
         private readonly IMessageBus _messageBus;
 
+        /// <summary>
+        /// Creates a provider that always returns the supplied bus instance.
+        /// </summary>
+        /// <param name="messageBus">Bus instance to return when <see cref="Resolve"/> is invoked.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="messageBus"/> is null.</exception>
         public FixedMessageBusProvider(IMessageBus messageBus)
         {
             _messageBus = messageBus ?? throw new ArgumentNullException(nameof(messageBus));
         }
 
+        /// <summary>
+        /// Resolves the configured message bus.
+        /// </summary>
+        /// <returns>The bus supplied during construction.</returns>
         public IMessageBus Resolve()
         {
             return _messageBus;

package/Runtime/Core/MessageBus/MessagingRegistration.cs

@@ -4,30 +4,84 @@ namespace DxMessaging.Core.MessageBus
     using System.Runtime.Serialization;
 
     /// <summary>
-    /// How the registration was performed.
+    /// Indicates whether a registration was added or removed.
     /// </summary>
     public enum RegistrationType
     {
+        /// <summary>
+        /// The registration was added to the bus.
+        /// </summary>
         Register,
+
+        /// <summary>
+        /// The registration was removed from the bus.
+        /// </summary>
         Deregister,
     }
 
     /// <summary>
-    /// Exact method of MessagingRegistration.
+    /// Exact registration category used when the handler was wired up.
     /// </summary>
     public enum RegistrationMethod
     {
+        /// <summary>
+        /// Registered as a targeted handler bound to a specific recipient.
+        /// </summary>
         Targeted,
+
+        /// <summary>
+        /// Registered as a global untargeted handler.
+        /// </summary>
         Untargeted,
+
+        /// <summary>
+        /// Registered as a broadcast handler bound to a specific source.
+        /// </summary>
         Broadcast,
+
+        /// <summary>
+        /// Registered as a broadcast handler without an explicit source.
+        /// </summary>
         BroadcastWithoutSource,
+
+        /// <summary>
+        /// Registered as a targeted handler that ignores the runtime target.
+        /// </summary>
         TargetedWithoutTargeting,
+
+        /// <summary>
+        /// Registered as a global catch-all handler.
+        /// </summary>
         GlobalAcceptAll,
+
+        /// <summary>
+        /// Registered as an interceptor (exact type recorded separately).
+        /// </summary>
         Interceptor,
+
+        /// <summary>
+        /// Registered as a post-processor for untargeted messages.
+        /// </summary>
         UntargetedPostProcessor,
+
+        /// <summary>
+        /// Registered as a post-processor for targeted messages.
+        /// </summary>
         TargetedPostProcessor,
+
+        /// <summary>
+        /// Registered as a post-processor for broadcast messages.
+        /// </summary>
         BroadcastPostProcessor,
+
+        /// <summary>
+        /// Registered as a post-processor for targeted messages that ignore the runtime target.
+        /// </summary>
         TargetedWithoutTargetingPostProcessor,
+
+        /// <summary>
+        /// Registered as a post-processor for broadcasts without explicit source information.
+        /// </summary>
         BroadcastWithoutSourcePostProcessor,
     }
 
@@ -88,6 +142,10 @@ namespace DxMessaging.Core.MessageBus
 #endif
         }
 
+        /// <summary>
+        /// Returns a descriptive string that includes key registration metadata for diagnostics.
+        /// </summary>
+        /// <returns>Human-readable summary of this registration entry.</returns>
         public override string ToString()
         {
             return new

package/Runtime/Core/MessageBus/RegistrationLog.cs

@@ -26,6 +26,12 @@ namespace DxMessaging.Core.MessageBus
 
         private bool _enabled;
 
+        /// <summary>
+        /// Creates a new registration log.
+        /// </summary>
+        /// <param name="enabled">
+        /// When <c>true</c>, logging starts immediately; otherwise call <see cref="Enabled"/> to enable later.
+        /// </param>
         public RegistrationLog(bool enabled = false)
         {
             _enabled = enabled;
@@ -92,6 +98,10 @@ namespace DxMessaging.Core.MessageBus
             return registrations.ToString();
         }
 
+        /// <summary>
+        /// Serializes the log using the default formatter (<see cref="MessagingRegistration.ToString"/>).
+        /// </summary>
+        /// <returns>String containing all recorded registrations.</returns>
         public override string ToString()
         {
             return ToString(null);

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)
@@ -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();
@@ -1965,6 +2027,11 @@ namespace DxMessaging.Core
         {
             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;
@@ -2345,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(
@@ -2356,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,
@@ -2379,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,
@@ -2402,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,
@@ -2425,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,

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)
         {
@@ -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();
+        }
     }
 }