com.wallstop-studios.dxmessaging 3.0.1 → 3.2.0

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

@@ -6,6 +6,6 @@ MonoImporter:
   defaultReferences: []
   executionOrder: 0
   icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+  userData:
+  assetBundleName:
+  assetBundleVariant:

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

@@ -6,6 +6,6 @@ MonoImporter:
   defaultReferences: []
   executionOrder: 0
   icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Runtime/Core/MessageBus/MessageBusRegistration.cs

@@ -0,0 +1,207 @@
+namespace DxMessaging.Core.MessageBus
+{
+    using System;
+    using System.Runtime.CompilerServices;
+
+    /// <summary>
+    /// Opaque subscription handle returned by the <see cref="IMessageBus"/> registration
+    /// methods (replacing the deregistration <see cref="Action"/> returned prior to v4).
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Hand the handle back to <see cref="IMessageBus.Deregister{T}"/> with the SAME
+    /// <c>T</c> you registered with to undo the registration. It is an opaque value token:
+    /// copy it freely, but do NOT inspect or persist its internals. Handles are
+    /// process-local, single-thread, and NOT serializable; a handle is meaningless after a
+    /// domain reload (its captured generation no longer matches, so deregistration becomes a
+    /// silent no-op) and is not portable across <see cref="IMessageBus"/> implementations.
+    /// </para>
+    /// <para>
+    /// The <c>default</c> value is the <see cref="None"/> sentinel; deregistering it is a
+    /// no-op. Custom <see cref="IMessageBus"/> implementers that do not wrap
+    /// <see cref="MessageBus"/> mint their own handles via the
+    /// <see cref="MessageBusRegistration(long, object)"/> constructor and read them back in
+    /// their own <see cref="IMessageBus.Deregister{T}"/> override (see <see cref="ExternalId"/>
+    /// / <see cref="ExternalState"/>).
+    /// </para>
+    /// </remarks>
+    public readonly struct MessageBusRegistration : IEquatable<MessageBusRegistration>
+    {
+        /// <summary>
+        /// Discriminates which bus store a handle deregisters from. The interceptor stores are
+        /// split because all three interceptor registrars log a single
+        /// <see cref="RegistrationMethod.Interceptor"/>, so <see cref="method"/> cannot pick
+        /// among them; the registering site (which knows the category) stamps the kind.
+        /// </summary>
+        internal enum Kind : byte
+        {
+            None = 0,
+            Handler,
+            UntargetedInterceptor,
+            TargetedInterceptor,
+            BroadcastInterceptor,
+            GlobalAcceptAll,
+            External,
+        }
+
+        /// <summary><see cref="Kind.None"/> =&gt; an invalid/empty handle; deregistration no-ops.</summary>
+        internal readonly Kind kind;
+
+        /// <summary>
+        /// Sink/scalar-vs-keyed discriminator AND the <see cref="RegistrationLog"/> row key for
+        /// the <see cref="Kind.Handler"/> shape. Unused (default) for the other kinds.
+        /// </summary>
+        internal readonly RegistrationMethod method;
+
+        /// <summary>The priority the handler/interceptor was registered at.</summary>
+        internal readonly int priority;
+
+        /// <summary>The <c>_resetGeneration</c> snapshot (reset/domain-reload guard, all kinds).</summary>
+        internal readonly long generation;
+
+        /// <summary>The <c>_globalSlotSweepGeneration</c> snapshot (<see cref="Kind.GlobalAcceptAll"/> only).</summary>
+        internal readonly long sweepGeneration;
+
+        /// <summary>
+        /// A unique per-registration stamp (the bus tick at registration time). It does NOT
+        /// participate in deregistration (the sink is re-resolved without it); its sole purpose is
+        /// to make two handles from distinct <c>Register*</c> calls compare UNEQUAL even when they
+        /// bump the same handler's refcount (same generation/caches/payload/priority/method). This
+        /// preserves the pre-v4 semantics where each registration returned a distinct deregistration
+        /// delegate, so handles remain safe to store in a set/map keyed by value.
+        /// </summary>
+        internal readonly long sequence;
+
+        /// <summary>
+        /// The captured identity anchor for the over-deregistration / stale-after-sweep checks:
+        /// the per-type <c>HandlerCache</c> (<see cref="Kind.Handler"/>) or the
+        /// <c>InterceptorCache</c> (interceptor kinds). Unused for
+        /// <see cref="Kind.GlobalAcceptAll"/> (reads the live global slot) and
+        /// <see cref="Kind.External"/>.
+        /// </summary>
+        internal readonly object capturedPrimary;
+
+        /// <summary>
+        /// The keyed (<see cref="Kind.Handler"/> targeted/broadcast) per-type context map captured
+        /// by identity; null otherwise.
+        /// </summary>
+        internal readonly object capturedSecondary;
+
+        /// <summary>
+        /// The deregistration payload: the <see cref="MessageHandler"/>
+        /// (<see cref="Kind.Handler"/> / <see cref="Kind.GlobalAcceptAll"/>), the interceptor
+        /// delegate (interceptor kinds), or the caller's external state
+        /// (<see cref="Kind.External"/>).
+        /// </summary>
+        internal readonly object payload;
+
+        /// <summary>
+        /// The keyed (<see cref="Kind.Handler"/> targeted/broadcast) target/source; <c>default</c>
+        /// otherwise (so no <c>UnityEngine.Object</c> is pinned for non-keyed kinds).
+        /// </summary>
+        internal readonly InstanceId context;
+
+        internal MessageBusRegistration(
+            Kind kind,
+            RegistrationMethod method,
+            int priority,
+            long generation,
+            long sweepGeneration,
+            long sequence,
+            object capturedPrimary,
+            object capturedSecondary,
+            object payload,
+            InstanceId context
+        )
+        {
+            this.kind = kind;
+            this.method = method;
+            this.priority = priority;
+            this.generation = generation;
+            this.sweepGeneration = sweepGeneration;
+            this.sequence = sequence;
+            this.capturedPrimary = capturedPrimary;
+            this.capturedSecondary = capturedSecondary;
+            this.payload = payload;
+            this.context = context;
+        }
+
+        /// <summary>
+        /// Mints an opaque handle for a custom (non-wrapping) <see cref="IMessageBus"/>
+        /// implementer. Pack any state required to deregister into
+        /// <paramref name="externalState"/> and an id into <paramref name="externalId"/>; read
+        /// them back via <see cref="ExternalId"/> / <see cref="ExternalState"/> in your own
+        /// <see cref="IMessageBus.Deregister{T}"/>. The built-in <see cref="MessageBus"/> treats
+        /// such a handle as a no-op (it owns no store for it).
+        /// </summary>
+        public MessageBusRegistration(long externalId, object externalState)
+            : this(
+                Kind.External,
+                default,
+                0,
+                externalId,
+                0L,
+                0L,
+                null,
+                null,
+                externalState,
+                default
+            ) { }
+
+        /// <summary>The invalid/empty handle. Deregistering it is a silent no-op.</summary>
+        public static readonly MessageBusRegistration None = default;
+
+        /// <summary>True when this handle represents a live registration (not <see cref="None"/>).</summary>
+        public bool IsValid => kind != Kind.None;
+
+        /// <summary>The external id supplied to <see cref="MessageBusRegistration(long, object)"/>; 0 for non-external handles.</summary>
+        public long ExternalId => kind == Kind.External ? generation : 0L;
+
+        /// <summary>The external state supplied to <see cref="MessageBusRegistration(long, object)"/>; null for non-external handles.</summary>
+        public object ExternalState => kind == Kind.External ? payload : null;
+
+        /// <inheritdoc />
+        public bool Equals(MessageBusRegistration other) =>
+            kind == other.kind
+            && method == other.method
+            && priority == other.priority
+            && generation == other.generation
+            && sweepGeneration == other.sweepGeneration
+            && sequence == other.sequence
+            && ReferenceEquals(capturedPrimary, other.capturedPrimary)
+            && ReferenceEquals(capturedSecondary, other.capturedSecondary)
+            && ReferenceEquals(payload, other.payload)
+            && context.Equals(other.context);
+
+        /// <inheritdoc />
+        public override bool Equals(object obj) =>
+            obj is MessageBusRegistration other && Equals(other);
+
+        /// <inheritdoc />
+        public override int GetHashCode()
+        {
+            // Reference-IDENTITY hashes for the captured refs keep parity with the
+            // ReferenceEquals comparisons in Equals: RuntimeHelpers.GetHashCode is the identity
+            // hash, so it stays consistent regardless of any virtual GetHashCode override (e.g.
+            // MessageHandler hashes by owner, and delegates by target/method) and avoids the
+            // unnecessary collisions those overrides would introduce. (null -> 0.)
+            int hash = (int)kind;
+            hash = (hash * 397) ^ (int)method;
+            hash = (hash * 397) ^ priority;
+            hash = (hash * 397) ^ generation.GetHashCode();
+            hash = (hash * 397) ^ sweepGeneration.GetHashCode();
+            hash = (hash * 397) ^ sequence.GetHashCode();
+            hash = (hash * 397) ^ RuntimeHelpers.GetHashCode(capturedPrimary);
+            hash = (hash * 397) ^ RuntimeHelpers.GetHashCode(capturedSecondary);
+            hash = (hash * 397) ^ RuntimeHelpers.GetHashCode(payload);
+            hash = (hash * 397) ^ context.GetHashCode();
+            return hash;
+        }
+
+        public static bool operator ==(MessageBusRegistration left, MessageBusRegistration right) =>
+            left.Equals(right);
+
+        public static bool operator !=(MessageBusRegistration left, MessageBusRegistration right) =>
+            !left.Equals(right);
+    }
+}

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

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

package/Runtime/Core/MessageBus/MessageRegistrationBuilder.cs

@@ -1,9 +1,45 @@
 namespace DxMessaging.Core.MessageBus
 {
     using System;
+    using System.Runtime.ExceptionServices;
     using System.Threading;
     using DxMessaging.Core;
 
+    /// <summary>
+    /// Exception thrown when <see cref="MessageRegistrationBuildOptions.ActivateOnBuild"/> fails and
+    /// the builder cannot fully clean up the partially constructed lease before returning control.
+    /// </summary>
+    public sealed class MessageRegistrationBuildException : Exception
+    {
+        internal MessageRegistrationBuildException(
+            string message,
+            MessageRegistrationLease lease,
+            Exception activationException,
+            Exception cleanupException
+        )
+            : base(message, activationException)
+        {
+            Lease = lease ?? throw new ArgumentNullException(nameof(lease));
+            ActivationException = activationException;
+            CleanupException = cleanupException;
+        }
+
+        /// <summary>
+        /// Lease that still owns retryable token cleanup. Dispose it after resolving the cleanup failure.
+        /// </summary>
+        public MessageRegistrationLease Lease { get; }
+
+        /// <summary>
+        /// Original exception raised while activating the lease.
+        /// </summary>
+        public Exception ActivationException { get; }
+
+        /// <summary>
+        /// Exception raised while attempting to clean up the partially constructed lease.
+        /// </summary>
+        public Exception CleanupException { get; }
+    }
+
     /// <summary>
     /// Options controlling how <see cref="MessageRegistrationBuilder"/> constructs registration tokens.
     /// </summary>
@@ -144,6 +180,8 @@ namespace DxMessaging.Core.MessageBus
         private readonly MessageRegistrationLifecycle _lifecycle;
         private bool _isActive;
         private bool _disposed;
+        private bool _deactivateHookInvoked;
+        private bool _disposeHookInvoked;
 
         internal MessageRegistrationLease(
             MessageRegistrationToken token,
@@ -159,6 +197,8 @@ namespace DxMessaging.Core.MessageBus
             _lifecycle = lifecycle;
             _isActive = false;
             _disposed = false;
+            _deactivateHookInvoked = false;
+            _disposeHookInvoked = false;
         }
 
         /// <summary>
@@ -199,13 +239,27 @@ namespace DxMessaging.Core.MessageBus
             }
 
             _messageHandler.active = true;
-            _token.Enable();
-            if (_lifecycle.OnActivate != null)
+            _deactivateHookInvoked = false;
+            try
             {
-                _lifecycle.OnActivate(_token);
+                _token.Enable();
+            }
+            catch
+            {
+                _messageHandler.active = _token.Enabled;
+                _isActive = _token.Enabled;
+                throw;
             }
 
+            // _isActive is set BEFORE the user callback runs so the lease's
+            // state matches the registrations even if OnActivate throws:
+            // Deactivate()/Dispose() can then always release the live
+            // registrations (a post-callback assignment left them wedged).
             _isActive = true;
+            if (_lifecycle.OnActivate != null)
+            {
+                _lifecycle.OnActivate(_token);
+            }
         }
 
         /// <summary>
@@ -218,14 +272,43 @@ namespace DxMessaging.Core.MessageBus
                 return;
             }
 
-            if (_lifecycle.OnDeactivate != null)
+            Exception deactivateFailure = null;
+            try
+            {
+                if (!_deactivateHookInvoked && _lifecycle.OnDeactivate != null)
+                {
+                    _deactivateHookInvoked = true;
+                    _lifecycle.OnDeactivate(_token);
+                }
+            }
+            catch (Exception exception)
             {
-                _lifecycle.OnDeactivate(_token);
+                deactivateFailure = exception;
+            }
+            finally
+            {
+                try
+                {
+                    try
+                    {
+                        _token.Disable();
+                    }
+                    catch (Exception exception)
+                    {
+                        deactivateFailure ??= exception;
+                    }
+                }
+                finally
+                {
+                    _messageHandler.active = _token.Enabled;
+                    _isActive = _token.Enabled;
+                }
             }
 
-            _token.Disable();
-            _messageHandler.active = false;
-            _isActive = false;
+            if (deactivateFailure != null)
+            {
+                ExceptionDispatchInfo.Capture(deactivateFailure).Throw();
+            }
         }
 
         /// <summary>
@@ -238,13 +321,58 @@ namespace DxMessaging.Core.MessageBus
                 return;
             }
 
-            Deactivate();
-            if (_lifecycle.OnDispose != null)
+            Exception disposeFailure = null;
+            bool tokenCleanupFailed = false;
+            try
+            {
+                try
+                {
+                    Deactivate();
+                }
+                catch (Exception exception)
+                {
+                    disposeFailure = exception;
+                }
+
+                if (!_disposeHookInvoked && _lifecycle.OnDispose != null)
+                {
+                    _disposeHookInvoked = true;
+                    try
+                    {
+                        _lifecycle.OnDispose(_token);
+                    }
+                    catch (Exception exception)
+                    {
+                        disposeFailure ??= exception;
+                    }
+                }
+            }
+            finally
             {
-                _lifecycle.OnDispose(_token);
+                try
+                {
+                    try
+                    {
+                        _token.Dispose();
+                    }
+                    catch (Exception exception)
+                    {
+                        tokenCleanupFailed = true;
+                        disposeFailure ??= exception;
+                    }
+                }
+                finally
+                {
+                    _messageHandler.active = _token.Enabled;
+                    _isActive = _token.Enabled;
+                    _disposed = !tokenCleanupFailed;
+                }
             }
 
-            _disposed = true;
+            if (disposeFailure != null)
+            {
+                ExceptionDispatchInfo.Capture(disposeFailure).Throw();
+            }
         }
 
         internal void InvokeBuildHook()
@@ -305,6 +433,7 @@ namespace DxMessaging.Core.MessageBus
         /// <param name="options">Options controlling bus selection, diagnostics, and lifecycle behavior.</param>
         /// <returns>A lease that wraps the created <see cref="MessageRegistrationToken"/>.</returns>
         /// <exception cref="ArgumentNullException">Thrown when <paramref name="options"/> is <see langword="null"/>.</exception>
+        /// <exception cref="MessageRegistrationBuildException">Thrown when ActivateOnBuild activation fails and automatic cleanup remains retryable.</exception>
         public MessageRegistrationLease Build(MessageRegistrationBuildOptions options)
         {
             if (options == null)
@@ -338,12 +467,56 @@ namespace DxMessaging.Core.MessageBus
 
             if (options.ActivateOnBuild)
             {
-                lease.Activate();
+                try
+                {
+                    lease.Activate();
+                }
+                catch (Exception exception)
+                {
+                    HandleActivateOnBuildFailure(lease, exception);
+                }
             }
 
             return lease;
         }
 
+        private static void HandleActivateOnBuildFailure(
+            MessageRegistrationLease lease,
+            Exception activationException
+        )
+        {
+            Exception cleanupException = null;
+            try
+            {
+                lease.Dispose();
+            }
+            catch (Exception exception)
+            {
+                cleanupException = exception;
+            }
+
+            if (lease.Token.Enabled)
+            {
+                throw new MessageRegistrationBuildException(
+                    "ActivateOnBuild failed and automatic lease cleanup did not complete. Dispose the Lease property after resolving the cleanup failure.",
+                    lease,
+                    activationException,
+                    cleanupException
+                );
+            }
+
+            if (cleanupException != null && MessagingDebug.enabled)
+            {
+                MessagingDebug.Log(
+                    LogLevel.Error,
+                    "ActivateOnBuild cleanup failed after activation failure: {0}",
+                    cleanupException
+                );
+            }
+
+            ExceptionDispatchInfo.Capture(activationException).Throw();
+        }
+
         private static InstanceId ResolveOwner(MessageRegistrationBuildOptions options)
         {
 #if UNITY_2021_3_OR_NEWER
@@ -359,7 +532,7 @@ namespace DxMessaging.Core.MessageBus
                     return component;
                 }
 
-                return new InstanceId(options.UnityOwner.GetInstanceID());
+                return new InstanceId(InstanceId.StableId(options.UnityOwner));
             }
 #endif
             if (options.Owner.HasValue)

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

@@ -6,6 +6,6 @@ MonoImporter:
   defaultReferences: []
   executionOrder: 0
   icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+  userData:
+  assetBundleName:
+  assetBundleVariant:

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

@@ -6,6 +6,6 @@ MonoImporter:
   defaultReferences: []
   executionOrder: 0
   icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+  userData:
+  assetBundleName:
+  assetBundleVariant:

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

@@ -6,6 +6,6 @@ MonoImporter:
   defaultReferences: []
   executionOrder: 0
   icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+  userData:
+  assetBundleName:
+  assetBundleVariant: