com.wallstop-studios.dxmessaging 2.1.1 → 2.1.3

package/Runtime/Core/InstanceId.cs

@@ -30,18 +30,24 @@ namespace DxMessaging.Core
 
         private readonly int _id;
 
-#if UNITY_2017_1_OR_NEWER
+#if UNITY_2021_3_OR_NEWER
         // ReSharper disable once InconsistentNaming
         public readonly UnityEngine.Object Object;
 #endif
 
+        /// <summary>
+        /// Creates an identifier that wraps the provided Unity instance ID.
+        /// </summary>
+        /// <param name="id">Unity instance ID to wrap.</param>
         public InstanceId(int id)
         {
             _id = id;
+#if UNITY_2021_3_OR_NEWER
             Object = null;
+#endif
         }
 
-#if UNITY_2017_1_OR_NEWER
+#if UNITY_2021_3_OR_NEWER
         private InstanceId(UnityEngine.Object unityObject)
         {
             _id = unityObject.GetInstanceID();
@@ -49,12 +55,22 @@ namespace DxMessaging.Core
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        /// <summary>
+        /// Converts a <see cref="UnityEngine.GameObject"/> reference into an <see cref="InstanceId"/>.
+        /// </summary>
+        /// <param name="gameObject">GameObject to wrap.</param>
+        /// <returns>Instance identifier representing <paramref name="gameObject"/>.</returns>
         public static implicit operator InstanceId(UnityEngine.GameObject gameObject)
         {
             return new InstanceId(gameObject);
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        /// <summary>
+        /// Converts a <see cref="UnityEngine.Component"/> reference into an <see cref="InstanceId"/>.
+        /// </summary>
+        /// <param name="component">Component to wrap.</param>
+        /// <returns>Instance identifier representing <paramref name="component"/>.</returns>
         public static implicit operator InstanceId(UnityEngine.Component component)
         {
             return new InstanceId(component);
@@ -62,26 +78,46 @@ namespace DxMessaging.Core
 #endif
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        /// <summary>
+        /// Checks for equality with another <see cref="InstanceId"/>.
+        /// </summary>
+        /// <param name="other">Other instance identifier.</param>
+        /// <returns><c>true</c> when both identifiers refer to the same Unity instance.</returns>
         public bool Equals(InstanceId other)
         {
             return _id == other._id;
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        /// <summary>
+        /// Checks for equality with an arbitrary object.
+        /// </summary>
+        /// <param name="other">Object to compare.</param>
+        /// <returns>
+        /// <c>true</c> when <paramref name="other"/> is an <see cref="InstanceId"/> representing the same Unity instance.
+        /// </returns>
         public override bool Equals(object other)
         {
             return other is InstanceId id && Equals(id);
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        /// <summary>
+        /// Gets a hash code suitable for dictionary or set lookups.
+        /// </summary>
+        /// <returns>Hash code derived from the underlying Unity instance ID.</returns>
         public override int GetHashCode()
         {
             return _id;
         }
 
+        /// <summary>
+        /// Returns a string representation that includes the Unity instance ID and, when available, the object name.
+        /// </summary>
+        /// <returns>Human-readable description of the identifier.</returns>
         public override string ToString()
         {
-#if UNITY_2017_1_OR_NEWER
+#if UNITY_2021_3_OR_NEWER
             UnityEngine.Object instance = Object;
             string objectName = instance == null ? string.Empty : instance.name;
             return new { Id = _id, Name = objectName }.ToString();
@@ -91,48 +127,100 @@ namespace DxMessaging.Core
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        /// <summary>
+        /// Determines whether two identifiers refer to the same Unity instance.
+        /// </summary>
+        /// <param name="lhs">Left-hand identifier.</param>
+        /// <param name="rhs">Right-hand identifier.</param>
+        /// <returns><c>true</c> when both identifiers represent the same value.</returns>
         public static bool operator ==(InstanceId lhs, InstanceId rhs)
         {
             return lhs._id == rhs._id;
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        /// <summary>
+        /// Determines whether two identifiers refer to different Unity instances.
+        /// </summary>
+        /// <param name="lhs">Left-hand identifier.</param>
+        /// <param name="rhs">Right-hand identifier.</param>
+        /// <returns><c>true</c> when the identifiers represent different values.</returns>
         public static bool operator !=(InstanceId lhs, InstanceId rhs)
         {
             return lhs._id != rhs._id;
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        /// <summary>
+        /// Compares two identifiers for ascending ordering.
+        /// </summary>
+        /// <param name="lhs">Left-hand identifier.</param>
+        /// <param name="rhs">Right-hand identifier.</param>
+        /// <returns><c>true</c> when <paramref name="lhs"/> precedes <paramref name="rhs"/>.</returns>
         public static bool operator <(InstanceId lhs, InstanceId rhs)
         {
             return lhs._id.CompareTo(rhs._id) < 0;
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        /// <summary>
+        /// Compares two identifiers for ascending ordering with equality.
+        /// </summary>
+        /// <param name="lhs">Left-hand identifier.</param>
+        /// <param name="rhs">Right-hand identifier.</param>
+        /// <returns>
+        /// <c>true</c> when <paramref name="lhs"/> precedes <paramref name="rhs"/> or both identifiers are equal.
+        /// </returns>
         public static bool operator <=(InstanceId lhs, InstanceId rhs)
         {
             return lhs._id.CompareTo(rhs._id) <= 0;
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        /// <summary>
+        /// Compares two identifiers for descending ordering.
+        /// </summary>
+        /// <param name="lhs">Left-hand identifier.</param>
+        /// <param name="rhs">Right-hand identifier.</param>
+        /// <returns><c>true</c> when <paramref name="lhs"/> follows <paramref name="rhs"/>.</returns>
         public static bool operator >(InstanceId lhs, InstanceId rhs)
         {
             return lhs._id.CompareTo(rhs._id) > 0;
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        /// <summary>
+        /// Compares two identifiers for descending ordering with equality.
+        /// </summary>
+        /// <param name="lhs">Left-hand identifier.</param>
+        /// <param name="rhs">Right-hand identifier.</param>
+        /// <returns>
+        /// <c>true</c> when <paramref name="lhs"/> follows <paramref name="rhs"/> or both identifiers are equal.
+        /// </returns>
         public static bool operator >=(InstanceId lhs, InstanceId rhs)
         {
             return lhs._id.CompareTo(rhs._id) >= 0;
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        /// <summary>
+        /// Compares this identifier with another identifier for ordering.
+        /// </summary>
+        /// <param name="other">Identifier to compare with.</param>
+        /// <returns>Relative ordering as defined by <see cref="IComparable{T}.CompareTo(T)"/>.</returns>
         public int CompareTo(InstanceId other)
         {
             return _id.CompareTo(other._id);
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        /// <summary>
+        /// Compares this identifier with an arbitrary object for ordering.
+        /// </summary>
+        /// <param name="rhs">Object to compare with.</param>
+        /// <returns>
+        /// Relative ordering when <paramref name="rhs"/> is an <see cref="InstanceId"/>; otherwise <c>-1</c>.
+        /// </returns>
         public int CompareTo(object rhs)
         {
             if (rhs is InstanceId other)

package/Runtime/Core/MessageBus/DiagnosticsTarget.cs

@@ -0,0 +1,31 @@
+namespace DxMessaging.Core.MessageBus
+{
+    using System;
+
+    /// <summary>
+    /// Flags describing which execution targets should enable diagnostics by default.
+    /// </summary>
+    [Flags]
+    public enum DiagnosticsTarget
+    {
+        /// <summary>
+        /// Diagnostics are disabled.
+        /// </summary>
+        Off = 0,
+
+        /// <summary>
+        /// Diagnostics should run while in the Unity editor.
+        /// </summary>
+        Editor = 1,
+
+        /// <summary>
+        /// Diagnostics should run while in player/runtime builds.
+        /// </summary>
+        Runtime = 2,
+
+        /// <summary>
+        /// Diagnostics should run in both editor and runtime environments.
+        /// </summary>
+        All = Editor | Runtime,
+    }
+}

package/Runtime/Core/MessageBus/DiagnosticsTarget.cs.meta

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

package/Runtime/Core/MessageBus/IMessageBus.cs

@@ -3,7 +3,11 @@ namespace DxMessaging.Core.MessageBus
     using System;
     using System.Threading;
     using Core;
+    using Extensions;
     using Messages;
+#if UNITY_2021_3_OR_NEWER
+    using UnityEngine;
+#endif
 
     /// <summary>
     /// Contract for a general-purpose message bus handling registration and dispatch.
@@ -41,31 +45,59 @@ namespace DxMessaging.Core.MessageBus
         /// <summary>
         /// Default diagnostics mode for newly created buses and tokens.
         /// </summary>
-        public static bool GlobalDiagnosticsMode { get; set; }
+        static DiagnosticsTarget GlobalDiagnosticsTargets { get; set; } = DiagnosticsTarget.Off;
+
+        [Obsolete("Use GlobalDiagnosticsTargets instead.")]
+        static bool GlobalDiagnosticsMode
+        {
+            get => GlobalDiagnosticsTargets != DiagnosticsTarget.Off;
+            set => GlobalDiagnosticsTargets = value ? DiagnosticsTarget.All : DiagnosticsTarget.Off;
+        }
 
         long EmissionId { get; }
 
         /// <summary>
         /// Default ring buffer size for emission history when diagnostics are enabled.
         /// </summary>
-        public static int GlobalMessageBufferSize { get; set; }
+        static int GlobalMessageBufferSize { get; set; }
 
         internal static int GlobalSequentialIndex = -1;
 
         protected static int GenerateNewGlobalSequentialIndex() =>
             Interlocked.Increment(ref GlobalSequentialIndex);
 
+        internal static bool ShouldEnableDiagnostics()
+        {
+            DiagnosticsTarget targets = GlobalDiagnosticsTargets;
+            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
+        }
+
         /// <summary>
         /// Whether diagnostics are recorded for this bus instance.
         /// </summary>
-        public bool DiagnosticsMode { get; }
+        bool DiagnosticsMode { get; }
 
-        public int RegisteredGlobalSequentialIndex { get; }
-        public int RegisteredBroadcast { get; }
+        int RegisteredGlobalSequentialIndex { get; }
+        int RegisteredBroadcast { get; }
 
-        public int RegisteredTargeted { get; }
+        int RegisteredTargeted { get; }
 
-        public int RegisteredUntargeted { get; }
+        int RegisteredUntargeted { get; }
 
         /// <summary>
         /// Interceptor delegate for untargeted messages to transform or cancel them.
@@ -73,7 +105,7 @@ namespace DxMessaging.Core.MessageBus
         /// <typeparam name="TMessage">Specific type of message.</typeparam>
         /// <param name="message">Message to consider.</param>
         /// <returns>True if the message should be processed, false if it should be skipped.</returns>
-        public delegate bool UntargetedInterceptor<TMessage>(ref TMessage message)
+        delegate bool UntargetedInterceptor<TMessage>(ref TMessage message)
             where TMessage : IUntargetedMessage;
 
         /// <summary>
@@ -83,10 +115,7 @@ namespace DxMessaging.Core.MessageBus
         /// <param name="target">Target of the message.</param>
         /// <param name="message">Message to consider.</param>
         /// <returns>True if the message should be processed, false if it should be skipped.</returns>
-        public delegate bool TargetedInterceptor<TMessage>(
-            ref InstanceId target,
-            ref TMessage message
-        )
+        delegate bool TargetedInterceptor<TMessage>(ref InstanceId target, ref TMessage message)
             where TMessage : ITargetedMessage;
 
         /// <summary>
@@ -96,10 +125,7 @@ namespace DxMessaging.Core.MessageBus
         /// <param name="source">Source of the message.</param>
         /// <param name="message">Message to consider.</param>
         /// <returns>True if the message should be processed, false if it should be skipped.</returns>
-        public delegate bool BroadcastInterceptor<TMessage>(
-            ref InstanceId source,
-            ref TMessage message
-        )
+        delegate bool BroadcastInterceptor<TMessage>(ref InstanceId source, ref TMessage message)
             where TMessage : IBroadcastMessage;
 
         /// <summary>
@@ -149,6 +175,7 @@ namespace DxMessaging.Core.MessageBus
         /// <typeparam name="T">Type of the BroadcastMessage to register.</typeparam>
         /// <param name="source">InstanceId of the source for BroadcastMessages to listen to.</param>
         /// <param name="messageHandler">MessageHandler to register to accept BroadcastMessages.</param>
+        /// <param name="priority"></param>
         /// <returns>The deregistration action. Should be invoked when the handler no longer wants to receive messages.</returns>
         Action RegisterSourcedBroadcast<T>(
             InstanceId source,
@@ -163,6 +190,7 @@ namespace DxMessaging.Core.MessageBus
         /// </summary>
         /// <typeparam name="T">Type of the BroadcastMessage to register.</typeparam>
         /// <param name="messageHandler">MessageHandler to register to accept BroadcastMessages.</param>
+        /// <param name="priority"></param>
         /// <returns>The deregistration action. Should be invoked when the handler no longer wants to receive messages.</returns>
         Action RegisterSourcedBroadcastWithoutSource<T>(
             MessageHandler messageHandler,