com.wallstop-studios.dxmessaging 2.1.9 → 3.0.1

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

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

package/Runtime/Core/MessageBus/IMessageBus.cs

@@ -22,10 +22,17 @@ namespace DxMessaging.Core.MessageBus
     /// </list>
     /// <para>Message categories:</para>
     /// <list type="bullet">
-    /// <item><description><see cref="Messages.IUntargetedMessage"/> — Global notifications.</description></item>
-    /// <item><description><see cref="Messages.ITargetedMessage"/> — Directed at a specific <see cref="InstanceId"/>.</description></item>
-    /// <item><description><see cref="Messages.IBroadcastMessage"/> — Emitted from a source for any listener.</description></item>
+    /// <item><description><see cref="Messages.IUntargetedMessage"/> -- Global notifications.</description></item>
+    /// <item><description><see cref="Messages.ITargetedMessage"/> -- Directed at a specific <see cref="InstanceId"/>.</description></item>
+    /// <item><description><see cref="Messages.IBroadcastMessage"/> -- Emitted from a source for any listener.</description></item>
     /// </list>
+    /// <para>
+    /// Contract note: emitting any message on a bus with no registered handlers must
+    /// be a silent no-op. Implementations must NOT throw, log, or otherwise surface
+    /// the empty-bus state to the caller. The
+    /// <c>LifecycleEdgeCasesTests.EmitOnEmptyBusIsSilentNoOp</c> test pins this
+    /// contract for every message kind.
+    /// </para>
     /// </remarks>
     /// <example>
     /// <code>
@@ -56,6 +63,21 @@ namespace DxMessaging.Core.MessageBus
 
         long EmissionId { get; }
 
+        /// <summary>
+        /// Reclaim empty message slots and pooled collections owned by this bus.
+        /// </summary>
+        /// <remarks>
+        /// Non-Unity and headless hosts must call this periodically when they need
+        /// deterministic reclamation. The automatic PlayerLoop sweep hook is only
+        /// installed on Unity 2021.3 or newer player/editor hosts.
+        /// </remarks>
+        /// <param name="force">
+        /// When true, ignores idle-age thresholds and drains shared pools to zero.
+        /// When false, only slots past the configured idle threshold are eligible.
+        /// </param>
+        /// <returns>Counts describing what was reclaimed.</returns>
+        TrimResult Trim(bool force = false);
+
         /// <summary>
         /// Default buffer size for message emission history.
         /// </summary>
@@ -112,12 +134,129 @@ namespace DxMessaging.Core.MessageBus
         bool DiagnosticsMode { get; }
 
         int RegisteredGlobalSequentialIndex { get; }
+
+        /// <summary>
+        /// Number of currently occupied per-message-type slots on this bus.
+        /// </summary>
+        int OccupiedTypeSlots { get; }
+
+        /// <summary>
+        /// Number of currently occupied per-context target/source slots on this bus.
+        /// </summary>
+        int OccupiedTargetSlots { get; }
+
+        /// <summary>
+        /// Result returned by <see cref="Trim"/>.
+        /// </summary>
+        readonly struct TrimResult : IEquatable<TrimResult>
+        {
+            public TrimResult(
+                int typeSlotsEvicted,
+                int targetSlotsEvicted,
+                int pooledCollectionsEvicted,
+                int liveTypeSlotsRemaining
+            )
+            {
+                TypeSlotsEvicted = typeSlotsEvicted;
+                TargetSlotsEvicted = targetSlotsEvicted;
+                PooledCollectionsEvicted = pooledCollectionsEvicted;
+                LiveTypeSlotsRemaining = liveTypeSlotsRemaining;
+            }
+
+            /// <summary>Number of typed-handler slots reset.</summary>
+            public int TypeSlotsEvicted { get; }
+
+            /// <summary>Number of bus target/source context entries removed.</summary>
+            public int TargetSlotsEvicted { get; }
+
+            /// <summary>Number of pooled collections dropped from shared pools.</summary>
+            public int PooledCollectionsEvicted { get; }
+
+            /// <summary>Number of occupied type slots remaining after trim.</summary>
+            public int LiveTypeSlotsRemaining { get; }
+
+            public bool Equals(TrimResult other) =>
+                TypeSlotsEvicted == other.TypeSlotsEvicted
+                && TargetSlotsEvicted == other.TargetSlotsEvicted
+                && PooledCollectionsEvicted == other.PooledCollectionsEvicted
+                && LiveTypeSlotsRemaining == other.LiveTypeSlotsRemaining;
+
+            public override bool Equals(object obj) => obj is TrimResult other && Equals(other);
+
+            public override int GetHashCode() =>
+                (
+                    TypeSlotsEvicted,
+                    TargetSlotsEvicted,
+                    PooledCollectionsEvicted,
+                    LiveTypeSlotsRemaining
+                ).GetHashCode();
+
+            public static bool operator ==(TrimResult left, TrimResult right) => left.Equals(right);
+
+            public static bool operator !=(TrimResult left, TrimResult right) =>
+                !left.Equals(right);
+
+            public override string ToString() =>
+                $"TrimResult(TypeSlotsEvicted={TypeSlotsEvicted}, TargetSlotsEvicted={TargetSlotsEvicted}, PooledCollectionsEvicted={PooledCollectionsEvicted}, LiveTypeSlotsRemaining={LiveTypeSlotsRemaining})";
+        }
+
         int RegisteredBroadcast { get; }
 
         int RegisteredTargeted { get; }
 
         int RegisteredUntargeted { get; }
 
+        /// <summary>
+        /// Total number of registered interceptors across all message kinds.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Counts the unique <c>(interceptor delegate, priority)</c> pairs registered via
+        /// <see cref="RegisterUntargetedInterceptor{T}"/>, <see cref="RegisterTargetedInterceptor{T}"/>,
+        /// and <see cref="RegisterBroadcastInterceptor{T}"/>. Test infrastructure such as
+        /// <c>LeakWatcher</c> reads this counter to detect interceptor handles that escape
+        /// a watched region. Single-thread contract: read on the same thread that drives dispatch.
+        /// </para>
+        /// <para>
+        /// Aggregated by walking the per-kind interceptor caches; the call is O(n) in the
+        /// number of message types known to the bus. Snapshot at the start of a tracked
+        /// region rather than reading in a hot loop.
+        /// </para>
+        /// </remarks>
+        int RegisteredInterceptors { get; }
+
+        /// <summary>
+        /// Total number of registered post-processors across all message kinds.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Sums per-message-type post-processor handler counts across the untargeted,
+        /// targeted, targeted-without-targeting, broadcast, and broadcast-without-source
+        /// post-processor sinks. Test infrastructure such as <c>LeakWatcher</c> reads this
+        /// counter to detect post-processor handles that escape a watched region. Same
+        /// single-thread contract as the other counters.
+        /// </para>
+        /// <para>
+        /// Aggregated on each read; prefer snapshotting at region boundaries instead of
+        /// polling every frame.
+        /// </para>
+        /// </remarks>
+        int RegisteredPostProcessors { get; }
+
+        /// <summary>
+        /// Number of registered global accept-all handlers on this bus.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Counts the distinct <see cref="MessageHandler"/> instances registered via
+        /// <see cref="RegisterGlobalAcceptAll"/>. Test infrastructure such as
+        /// <c>LeakWatcher</c> reads this counter to detect global accept-all handles
+        /// that escape a watched region. Same single-thread contract as the other
+        /// counters.
+        /// </para>
+        /// </remarks>
+        int RegisteredGlobalAcceptAll { get; }
+
         /// <summary>
         /// Interceptor delegate for untargeted messages to transform or cancel them.
         /// </summary>
@@ -170,6 +309,16 @@ namespace DxMessaging.Core.MessageBus
         /// <param name="messageHandler">MessageHandler to register the TargetedMessages of the specified type.</param>
         /// <param name="priority">Priority at which to run; lower runs earlier.</param>
         /// <returns>The deregistration action. Invoke when the handler no longer wants to receive the messages.</returns>
+        /// <remarks>
+        /// To preserve frozen dispatch snapshots during in-flight emissions, the per-MessageHandler
+        /// typed-cache for <c>(target, priority)</c> is NOT removed when the last registration at
+        /// that pair is deregistered. Empty entries persist for the lifetime of the owning
+        /// MessageHandler. For typical Unity usage with a small fixed set of priorities and a
+        /// bounded set of long-lived target ids the residual footprint is trivial; code that
+        /// registers per-ephemeral-target (e.g. a global service that listens to messages targeted
+        /// at every spawned GameObject) should prefer <see cref="RegisterTargetedWithoutTargeting{T}"/>
+        /// or recycle MessageHandlers to avoid unbounded inner-dictionary growth.
+        /// </remarks>
         Action RegisterTargeted<T>(
             InstanceId target,
             MessageHandler messageHandler,
@@ -196,6 +345,16 @@ namespace DxMessaging.Core.MessageBus
         /// <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>
+        /// <remarks>
+        /// To preserve frozen dispatch snapshots during in-flight emissions, the per-MessageHandler
+        /// typed-cache for <c>(source, priority)</c> is NOT removed when the last registration at
+        /// that pair is deregistered. Empty entries persist for the lifetime of the owning
+        /// MessageHandler. For typical Unity usage with a small fixed set of priorities and a
+        /// bounded set of long-lived source ids the residual footprint is trivial; code that
+        /// registers per-ephemeral-source (e.g. a global service that listens to broadcasts from
+        /// every spawned GameObject) should prefer <see cref="RegisterSourcedBroadcastWithoutSource{T}"/>
+        /// or recycle MessageHandlers to avoid unbounded inner-dictionary growth.
+        /// </remarks>
         Action RegisterSourcedBroadcast<T>(
             InstanceId source,
             MessageHandler messageHandler,
@@ -243,6 +402,11 @@ namespace DxMessaging.Core.MessageBus
         ///         param1: Current message instance by reference
         ///     And returns: true if message handling should continue, false if message handling should be stopped.
         /// </note>
+        /// <remarks>
+        /// Interceptor delegates registered with this method are retained for the bus lifetime.
+        /// Calling the returned deregistration action removes the interceptor from dispatch, but
+        /// the delegate reference may remain until the final deregistration of that interceptor.
+        /// </remarks>
         /// <returns>The deregistration action. Should be invoked when the handler no longer wants to intercept messages.</returns>
         Action RegisterUntargetedInterceptor<T>(
             UntargetedInterceptor<T> interceptor,
@@ -268,6 +432,11 @@ namespace DxMessaging.Core.MessageBus
         ///         param1: Current message instance by reference
         ///     And returns: true if message handling should continue, false if message handling should be stopped.
         /// </note>
+        /// <remarks>
+        /// Interceptor delegates registered with this method are retained for the bus lifetime.
+        /// Calling the returned deregistration action removes the interceptor from dispatch, but
+        /// the delegate reference may remain until the final deregistration of that interceptor.
+        /// </remarks>
         /// <returns>The deregistration action. Should be invoked when the handler no longer wants to intercept messages.</returns>
         Action RegisterTargetedInterceptor<T>(TargetedInterceptor<T> interceptor, int priority = 0)
             where T : ITargetedMessage;
@@ -290,6 +459,11 @@ namespace DxMessaging.Core.MessageBus
         ///         param1: Current message instance by reference
         ///     And returns: true if message handling should continue, false if message handling should be stopped.
         /// </note>
+        /// <remarks>
+        /// Interceptor delegates registered with this method are retained for the bus lifetime.
+        /// Calling the returned deregistration action removes the interceptor from dispatch, but
+        /// the delegate reference may remain until the final deregistration of that interceptor.
+        /// </remarks>
         /// <returns>The deregistration action. Should be invoked when the handler no longer wants to intercept messages.</returns>
         Action RegisterBroadcastInterceptor<T>(
             BroadcastInterceptor<T> interceptor,

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

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

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

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

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

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

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

@@ -0,0 +1,16 @@
+namespace DxMessaging.Core.MessageBus.Internal
+{
+    /// <summary>
+    /// Const-int positions into <c>MessageBus._contextSinks[]</c>. Every
+    /// position is populated; there are no reserved slots.
+    /// </summary>
+    internal static class BusContextIndex
+    {
+        public const int TargetedHandleDefault = 0;
+        public const int BroadcastHandleDefault = 1;
+        public const int TargetedPostProcessDefault = 2;
+        public const int BroadcastPostProcessDefault = 3;
+
+        public const int Length = 4;
+    }
+}

package/Runtime/Core/MessageBus/Internal/BusContextIndex.cs.meta

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

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

@@ -0,0 +1,40 @@
+namespace DxMessaging.Core.MessageBus.Internal
+{
+    /// <summary>
+    /// Const-int positions into <c>MessageBus._scalarSinks[]</c>. Indices are
+    /// hand-written so call sites inline as immediate operands. Array lengths,
+    /// populated-non-null slot identities, and reserved-null slot identities
+    /// are validated in DEBUG builds via <c>MessageBus.ValidateSinkArrays()</c>.
+    /// </summary>
+    /// <remarks>
+    /// Slot 0 (<see cref="UntargetedHandleDefault"/>) holds the
+    /// <c>RegisterUntargeted</c> Handle-phase cache.
+    /// Slot 1 (<see cref="BroadcastHandleWithoutContext"/>) holds the
+    /// <c>RegisterSourcedBroadcastWithoutSource</c> Handle-phase cache.
+    /// Slot 2 (<see cref="TargetedHandleWithoutContext"/>) holds the
+    /// <c>RegisterTargetedWithoutTargeting</c> Handle-phase cache.
+    /// Slot 3 (<see cref="UntargetedPostProcessDefault"/>) holds the
+    /// <c>RegisterUntargetedPostProcessor</c> PostProcess-phase cache.
+    /// Slot 4 (<see cref="TargetedPostProcessWithoutContext"/>) holds the
+    /// <c>RegisterTargetedWithoutTargetingPostProcessor</c> PostProcess-phase cache.
+    /// Slot 5 (<see cref="BroadcastPostProcessWithoutContext"/>) holds the
+    /// <c>RegisterBroadcastWithoutSourcePostProcessor</c> PostProcess-phase cache.
+    /// Slots 6-7 (<see cref="Reserved6"/>, <see cref="Reserved7"/>) are permanent
+    /// future-expansion stubs and remain null.
+    /// </remarks>
+    internal static class BusSinkIndex
+    {
+        // "WithoutContext" unifies the legacy "WithoutTargeting" (Targeted) and
+        // "WithoutSource" (Broadcast) per-axis variants -- both lack an InstanceId.
+        public const int UntargetedHandleDefault = 0;
+        public const int BroadcastHandleWithoutContext = 1;
+        public const int TargetedHandleWithoutContext = 2;
+        public const int UntargetedPostProcessDefault = 3;
+        public const int TargetedPostProcessWithoutContext = 4;
+        public const int BroadcastPostProcessWithoutContext = 5;
+        public const int Reserved6 = 6;
+        public const int Reserved7 = 7;
+
+        public const int Length = 8;
+    }
+}

package/Runtime/Core/MessageBus/Internal/BusSinkIndex.cs.meta

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