com.wallstop-studios.dxmessaging 2.1.2 → 2.1.3

package/Runtime/Core/Helper/MessageCache.cs

@@ -33,6 +33,10 @@ namespace DxMessaging.Core.Helper
             }
 
             [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            /// <summary>
+            /// Advances the enumerator to the next cached value.
+            /// </summary>
+            /// <returns><c>true</c> if another non-null value exists; otherwise <c>false</c>.</returns>
             public bool MoveNext()
             {
                 List<TValue> values = _cache._values;
@@ -55,12 +59,18 @@ namespace DxMessaging.Core.Helper
             object IEnumerator.Current => Current;
 
             [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            /// <summary>
+            /// Resets the enumerator to the position before the first element.
+            /// </summary>
             public void Reset()
             {
                 _index = -1;
                 _current = default;
             }
 
+            /// <summary>
+            /// Releases resources held by the enumerator.
+            /// </summary>
             public void Dispose() { }
         }
 
@@ -179,6 +189,12 @@ namespace DxMessaging.Core.Helper
             return GetEnumerator();
         }
 
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        internal void Clear()
+        {
+            _values.Clear();
+        }
+
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         private void FillToIndex(int index)
         {

package/Runtime/Core/Helper/MessageHelperIndexer.cs

@@ -1,8 +1,80 @@
 namespace DxMessaging.Core.Helper
 {
+    using System;
+    using System.Collections.Generic;
+
     public static class MessageHelperIndexer
     {
+        internal readonly struct MessageHelperIndexerState
+        {
+            internal readonly int _totalMessages;
+
+            internal readonly Dictionary<Type, int> _sequentialIds;
+
+            internal MessageHelperIndexerState(
+                int totalMessages,
+                Dictionary<Type, int> sequentialIds
+            )
+            {
+                _totalMessages = totalMessages;
+                _sequentialIds = sequentialIds;
+            }
+        }
+
+        private static readonly object ResetLock = new();
+        private static readonly HashSet<Type> RegisteredTypes = new();
+        private static readonly Dictionary<Type, Func<int, int>> StateManipulationByType = new();
+
         internal static int TotalMessages = 0;
+
+        internal static void RegisterType(Type messageType, Func<int, int> idProducer)
+        {
+            if (messageType == null)
+            {
+                return;
+            }
+
+            lock (ResetLock)
+            {
+                if (!RegisteredTypes.Add(messageType))
+                {
+                    return;
+                }
+
+                StateManipulationByType[messageType] = idProducer;
+            }
+        }
+
+        internal static MessageHelperIndexerState CaptureState()
+        {
+            lock (ResetLock)
+            {
+                Dictionary<Type, int> snapshot = new(RegisteredTypes.Count);
+                return new MessageHelperIndexerState(TotalMessages, snapshot);
+            }
+        }
+
+        internal static void RestoreState(MessageHelperIndexerState state)
+        {
+            lock (ResetLock)
+            {
+                TotalMessages = state._totalMessages;
+                foreach (KeyValuePair<Type, Func<int, int>> entry in StateManipulationByType)
+                {
+                    Type type = entry.Key;
+                    Func<int, int> manipulationAction = entry.Value;
+                    if (
+                        state._sequentialIds == null
+                        || !state._sequentialIds.TryGetValue(type, out int value)
+                    )
+                    {
+                        value = -1;
+                    }
+
+                    manipulationAction(value);
+                }
+            }
+        }
     }
 
     public static class MessageHelperIndexer<TMessage>
@@ -10,5 +82,10 @@ namespace DxMessaging.Core.Helper
     {
         // ReSharper disable once StaticMemberInGenericType
         internal static int SequentialId = -1;
+
+        static MessageHelperIndexer()
+        {
+            MessageHelperIndexer.RegisterType(typeof(TMessage), value => SequentialId = value);
+        }
     }
 }

package/Runtime/Core/InstanceId.cs

@@ -35,6 +35,10 @@ namespace DxMessaging.Core
         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;
@@ -51,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);
@@ -64,23 +78,43 @@ 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_2021_3_OR_NEWER
@@ -93,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,