com.wallstop-studios.dxmessaging 2.2.0 → 3.0.1

package/Runtime/Core/Pooling/DxPools.cs

@@ -0,0 +1,157 @@
+namespace DxMessaging.Core.Pooling
+{
+    using System.Collections.Generic;
+    using DxMessaging.Core.Internal;
+#if UNITY_2021_3_OR_NEWER
+    using Configuration;
+#endif
+
+    /// <summary>
+    /// Static, single-threaded pool registry shared by the bus and handler
+    /// subsystems. Instantiated lazily on first use; reconfigured by
+    /// <see cref="Configure"/> when the runtime settings asset changes.
+    /// </summary>
+    /// <remarks>
+    /// Each pool returns the per-entry recycle action that clears the entry
+    /// before re-use, so callers do not need to remember to <c>Clear()</c>
+    /// before <c>Return</c>. <c>OnEvicted</c> currently does nothing -- entries
+    /// are dropped on cap overflow and the GC reclaims them.
+    /// </remarks>
+    internal static class DxPools
+    {
+        // Mirrors DxMessagingRuntimeSettings.DefaultBufferMaxDistinctEntries; updated by Configure().
+        // Kept as a local constant so DxPools' field initializers don't depend on Unity types.
+        private const int DefaultMaxRetained = 512;
+
+        internal static readonly CollectionPool<Dictionary<InstanceId, object>> InstanceIdDicts =
+            new(
+                maxRetained: DefaultMaxRetained,
+                useLru: true,
+                factory: () => new Dictionary<InstanceId, object>(),
+                onRecycled: dict => dict.Clear()
+            );
+
+        internal static readonly CollectionPool<List<InstanceId>> InstanceIdLists = new(
+            maxRetained: DefaultMaxRetained,
+            useLru: true,
+            factory: () => new List<InstanceId>(),
+            onRecycled: list => list.Clear()
+        );
+
+        internal static readonly CollectionPool<HashSet<InstanceId>> InstanceIdSets = new(
+            maxRetained: DefaultMaxRetained,
+            useLru: true,
+            factory: () => new HashSet<InstanceId>(),
+            onRecycled: set => set.Clear()
+        );
+
+        internal static readonly CollectionPool<List<object>> ObjectLists = new(
+            maxRetained: DefaultMaxRetained,
+            useLru: true,
+            factory: () => new List<object>(),
+            onRecycled: list => list.Clear()
+        );
+
+        internal static readonly CollectionPool<Stack<object>> ObjectStacks = new(
+            maxRetained: DefaultMaxRetained,
+            useLru: true,
+            factory: () => new Stack<object>(),
+            onRecycled: stack => stack.Clear()
+        );
+
+        internal static readonly CollectionPool<HashSet<int>> IntSets = new(
+            maxRetained: DefaultMaxRetained,
+            useLru: true,
+            factory: () => new HashSet<int>(),
+            onRecycled: set => set.Clear()
+        );
+
+        internal static readonly CollectionPool<
+            Dictionary<InstanceId, Dictionary<int, IHandlerActionCache>>
+        > TypedHandlerContextDicts = new(
+            maxRetained: DefaultMaxRetained,
+            useLru: true,
+            factory: () => new Dictionary<InstanceId, Dictionary<int, IHandlerActionCache>>(),
+            onRecycled: dict => dict.Clear()
+        );
+
+        internal static readonly CollectionPool<
+            Dictionary<int, IHandlerActionCache>
+        > TypedHandlerPriorityDicts = new(
+            maxRetained: DefaultMaxRetained,
+            useLru: true,
+            factory: () => new Dictionary<int, IHandlerActionCache>(),
+            onRecycled: dict => dict.Clear()
+        );
+
+        /// <summary>
+        /// Trim every pool. <paramref name="force"/> drains pools to zero;
+        /// otherwise each pool is trimmed to its current cap (a no-op unless the
+        /// cap was lowered). Returns total evicted count.
+        /// </summary>
+        internal static int TrimAll(bool force)
+        {
+            int evicted = 0;
+            evicted += InstanceIdDicts.Trim(force ? 0 : InstanceIdDicts.MaxRetained);
+            evicted += InstanceIdLists.Trim(force ? 0 : InstanceIdLists.MaxRetained);
+            evicted += InstanceIdSets.Trim(force ? 0 : InstanceIdSets.MaxRetained);
+            evicted += ObjectLists.Trim(force ? 0 : ObjectLists.MaxRetained);
+            evicted += ObjectStacks.Trim(force ? 0 : ObjectStacks.MaxRetained);
+            evicted += IntSets.Trim(force ? 0 : IntSets.MaxRetained);
+            evicted += TypedHandlerContextDicts.Trim(
+                force ? 0 : TypedHandlerContextDicts.MaxRetained
+            );
+            evicted += TypedHandlerPriorityDicts.Trim(
+                force ? 0 : TypedHandlerPriorityDicts.MaxRetained
+            );
+            return evicted;
+        }
+
+#if UNITY_2021_3_OR_NEWER
+        /// <summary>
+        /// Re-apply caps from the supplied settings. Lowering a cap immediately
+        /// trims; raising a cap takes effect on subsequent returns.
+        /// </summary>
+        internal static void Configure(DxMessagingRuntimeSettings settings)
+        {
+            if (settings == null)
+            {
+                throw new System.ArgumentNullException(nameof(settings));
+            }
+            int cap = settings.BufferMaxDistinctEntries;
+            bool useLru = settings.BufferUseLruEviction;
+            InstanceIdDicts.UseLru = useLru;
+            InstanceIdLists.UseLru = useLru;
+            InstanceIdSets.UseLru = useLru;
+            ObjectLists.UseLru = useLru;
+            ObjectStacks.UseLru = useLru;
+            IntSets.UseLru = useLru;
+            TypedHandlerContextDicts.UseLru = useLru;
+            TypedHandlerPriorityDicts.UseLru = useLru;
+            InstanceIdDicts.MaxRetained = cap;
+            InstanceIdLists.MaxRetained = cap;
+            InstanceIdSets.MaxRetained = cap;
+            ObjectLists.MaxRetained = cap;
+            ObjectStacks.MaxRetained = cap;
+            IntSets.MaxRetained = cap;
+            TypedHandlerContextDicts.MaxRetained = cap;
+            TypedHandlerPriorityDicts.MaxRetained = cap;
+        }
+#endif
+
+        /// <summary>Aggregate snapshot of every pool's diagnostics.</summary>
+        internal static PoolDiagnosticsSnapshot DescribeAll()
+        {
+            return new PoolDiagnosticsSnapshot(
+                InstanceIdDicts.Snapshot(),
+                InstanceIdLists.Snapshot(),
+                InstanceIdSets.Snapshot(),
+                ObjectLists.Snapshot(),
+                ObjectStacks.Snapshot(),
+                IntSets.Snapshot(),
+                TypedHandlerContextDicts.Snapshot(),
+                TypedHandlerPriorityDicts.Snapshot()
+            );
+        }
+    }
+}

package/Runtime/Core/Pooling/DxPools.cs.meta

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

package/Runtime/Core/Pooling/EvictionPlayerLoopHook.cs

@@ -0,0 +1,106 @@
+#if UNITY_2021_3_OR_NEWER
+namespace DxMessaging.Core.Pooling
+{
+    using System;
+    using MessageBus;
+    using UnityEngine;
+    using UnityEngine.LowLevel;
+    using UnityEngine.PlayerLoop;
+
+    /// <summary>
+    /// Unity PlayerLoop bridge that gives idle eviction a cadence even when no
+    /// messages are emitted.
+    /// </summary>
+    internal static class EvictionPlayerLoopHook
+    {
+        private static readonly Type HookType = typeof(EvictionPlayerLoopHook);
+
+        [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
+        private static void Install()
+        {
+            PlayerLoopSystem root = PlayerLoop.GetCurrentPlayerLoop();
+            if (InstallInto(ref root))
+            {
+                PlayerLoop.SetPlayerLoop(root);
+            }
+        }
+
+        internal static bool InstallInto(ref PlayerLoopSystem root)
+        {
+            if (ContainsHook(root))
+            {
+                return false;
+            }
+
+            PlayerLoopSystem hook = new PlayerLoopSystem
+            {
+                type = HookType,
+                updateDelegate = SweepIdleBuses,
+            };
+
+            return InsertUnder<Update>(ref root, hook);
+        }
+
+        private static void SweepIdleBuses()
+        {
+            MessageBus.SweepIdleBusesFromPlayerLoop();
+        }
+
+        internal static bool ContainsHook(PlayerLoopSystem system)
+        {
+            if (system.type == HookType)
+            {
+                return true;
+            }
+
+            PlayerLoopSystem[] subsystems = system.subSystemList;
+            if (subsystems == null)
+            {
+                return false;
+            }
+
+            for (int i = 0; i < subsystems.Length; ++i)
+            {
+                if (ContainsHook(subsystems[i]))
+                {
+                    return true;
+                }
+            }
+
+            return false;
+        }
+
+        private static bool InsertUnder<TTarget>(ref PlayerLoopSystem system, PlayerLoopSystem hook)
+        {
+            if (system.type == typeof(TTarget))
+            {
+                PlayerLoopSystem[] oldList =
+                    system.subSystemList ?? Array.Empty<PlayerLoopSystem>();
+                PlayerLoopSystem[] newList = new PlayerLoopSystem[oldList.Length + 1];
+                Array.Copy(oldList, newList, oldList.Length);
+                newList[oldList.Length] = hook;
+                system.subSystemList = newList;
+                return true;
+            }
+
+            PlayerLoopSystem[] subsystems = system.subSystemList;
+            if (subsystems == null)
+            {
+                return false;
+            }
+
+            for (int i = 0; i < subsystems.Length; ++i)
+            {
+                PlayerLoopSystem child = subsystems[i];
+                if (InsertUnder<TTarget>(ref child, hook))
+                {
+                    subsystems[i] = child;
+                    return true;
+                }
+            }
+
+            return false;
+        }
+    }
+}
+#endif

package/Runtime/Core/Pooling/EvictionPlayerLoopHook.cs.meta

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

package/Runtime/Core/Pooling/IDxMessagingClock.cs

@@ -0,0 +1,18 @@
+namespace DxMessaging.Core.Pooling
+{
+    /// <summary>
+    /// Abstraction over a monotonic wall-clock used by the eviction sweeper to
+    /// decide whether enough time has elapsed since the last sweep. Implementations
+    /// must be cheap (single field read or call) because sampled idle-sweep gates
+    /// sit on the emit path.
+    /// </summary>
+    public interface IDxMessagingClock
+    {
+        /// <summary>
+        /// Current time in seconds. Must be non-decreasing within a single
+        /// AppDomain. Implementations may have frame-grained or millisecond-grained
+        /// resolution; the eviction sweeper tolerates either.
+        /// </summary>
+        double NowSeconds { get; }
+    }
+}

package/Runtime/Core/Pooling/IDxMessagingClock.cs.meta

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

package/Runtime/Core/Pooling/PoolDiagnosticsSnapshot.cs

@@ -0,0 +1,55 @@
+namespace DxMessaging.Core.Pooling
+{
+    /// <summary>
+    /// Aggregate snapshot of every <see cref="DxPools"/> pool. Returned by
+    /// <see cref="DxPools.DescribeAll"/>. Pool names are stable, human-readable
+    /// strings safe to log.
+    /// </summary>
+    internal readonly struct PoolDiagnosticsSnapshot
+    {
+        /// <summary><c>Dictionary&lt;InstanceId, object&gt;</c> pool diagnostics.</summary>
+        public readonly CollectionPoolDiagnostics InstanceIdDicts;
+
+        /// <summary><c>List&lt;InstanceId&gt;</c> pool diagnostics.</summary>
+        public readonly CollectionPoolDiagnostics InstanceIdLists;
+
+        /// <summary><c>HashSet&lt;InstanceId&gt;</c> pool diagnostics.</summary>
+        public readonly CollectionPoolDiagnostics InstanceIdSets;
+
+        /// <summary><c>List&lt;object&gt;</c> pool diagnostics.</summary>
+        public readonly CollectionPoolDiagnostics ObjectLists;
+
+        /// <summary><c>Stack&lt;object&gt;</c> pool diagnostics.</summary>
+        public readonly CollectionPoolDiagnostics ObjectStacks;
+
+        /// <summary><c>HashSet&lt;int&gt;</c> pool diagnostics.</summary>
+        public readonly CollectionPoolDiagnostics IntSets;
+
+        /// <summary>Typed handler <c>InstanceId -&gt; priority-cache</c> dictionary pool diagnostics.</summary>
+        public readonly CollectionPoolDiagnostics TypedHandlerContextDicts;
+
+        /// <summary>Typed handler priority-cache dictionary pool diagnostics.</summary>
+        public readonly CollectionPoolDiagnostics TypedHandlerPriorityDicts;
+
+        internal PoolDiagnosticsSnapshot(
+            CollectionPoolDiagnostics instanceIdDicts,
+            CollectionPoolDiagnostics instanceIdLists,
+            CollectionPoolDiagnostics instanceIdSets,
+            CollectionPoolDiagnostics objectLists,
+            CollectionPoolDiagnostics objectStacks,
+            CollectionPoolDiagnostics intSets,
+            CollectionPoolDiagnostics typedHandlerContextDicts,
+            CollectionPoolDiagnostics typedHandlerPriorityDicts
+        )
+        {
+            InstanceIdDicts = instanceIdDicts;
+            InstanceIdLists = instanceIdLists;
+            InstanceIdSets = instanceIdSets;
+            ObjectLists = objectLists;
+            ObjectStacks = objectStacks;
+            IntSets = intSets;
+            TypedHandlerContextDicts = typedHandlerContextDicts;
+            TypedHandlerPriorityDicts = typedHandlerPriorityDicts;
+        }
+    }
+}

package/Runtime/Core/Pooling/PoolDiagnosticsSnapshot.cs.meta

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

package/Runtime/Core/Pooling/StopwatchClock.cs

@@ -0,0 +1,27 @@
+namespace DxMessaging.Core.Pooling
+{
+    using System.Diagnostics;
+    using System.Runtime.CompilerServices;
+
+    /// <summary>
+    /// Default <see cref="IDxMessagingClock"/> backed by a process-lifetime
+    /// <see cref="Stopwatch"/>. Monotonic and Unity-agnostic so it works in
+    /// EditMode, PlayMode, and standalone test harnesses.
+    /// </summary>
+    public sealed class StopwatchClock : IDxMessagingClock
+    {
+        /// <summary>Shared instance. Stopwatch is lock-free and safe to share.</summary>
+        public static readonly StopwatchClock Instance = new();
+
+        private static readonly double TicksToSeconds = 1.0 / Stopwatch.Frequency;
+
+        private readonly Stopwatch _stopwatch = Stopwatch.StartNew();
+
+        /// <inheritdoc />
+        public double NowSeconds
+        {
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            get => _stopwatch.ElapsedTicks * TicksToSeconds;
+        }
+    }
+}

package/Runtime/Core/Pooling/StopwatchClock.cs.meta

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

package/Runtime/Core/Pooling/UnityRealtimeClock.cs

@@ -0,0 +1,31 @@
+namespace DxMessaging.Core.Pooling
+{
+#if UNITY_2021_3_OR_NEWER
+    using System.Runtime.CompilerServices;
+    using UnityEngine;
+
+    /// <summary>
+    /// Unity-only <see cref="IDxMessagingClock"/> backed by
+    /// <see cref="Time.realtimeSinceStartupAsDouble"/>. Use this when sweep cadence
+    /// should follow Unity wall time rather than the AppDomain Stopwatch (Stopwatch
+    /// keeps running across editor pause; Time.realtimeSinceStartupAsDouble also
+    /// runs across pause but is the canonical Unity clock).
+    /// </summary>
+    /// <remarks>
+    /// Must be invoked from the Unity main thread; the underlying <c>Time</c>
+    /// API throws when called from worker threads.
+    /// </remarks>
+    public sealed class UnityRealtimeClock : IDxMessagingClock
+    {
+        /// <summary>Shared instance.</summary>
+        public static readonly UnityRealtimeClock Instance = new();
+
+        /// <inheritdoc />
+        public double NowSeconds
+        {
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            get => Time.realtimeSinceStartupAsDouble;
+        }
+    }
+#endif
+}

package/Runtime/Core/Pooling/UnityRealtimeClock.cs.meta

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

package/Runtime/Core/Pooling.meta

@@ -0,0 +1,9 @@
+fileFormatVersion: 2
+guid: fc38a1d26fb3ceb14f2c2fa031b313a1
+timeCreated: 1777840186
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Core.meta

@@ -1,8 +1,8 @@
-fileFormatVersion: 2
-guid: b58cce05d4f7d9447a63e82e2169f927
-folderAsset: yes
-DefaultImporter:
-  externalObjects: {}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: b58cce05d4f7d9447a63e82e2169f927
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/Unity/CurrentGlobalMessageBusProvider.cs.meta

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

package/Runtime/Unity/DxMessagingRuntimeInitializer.cs.meta

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

package/Runtime/Unity/InitialGlobalMessageBusProvider.cs.meta

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

package/Runtime/Unity/Integrations/Reflex/AssemblyInfo.cs.meta

@@ -1,3 +1,3 @@
-fileFormatVersion: 2
-guid: 978915f0cb9d43d99e46455ff38dc528
+fileFormatVersion: 2
+guid: 978915f0cb9d43d99e46455ff38dc528
 timeCreated: 1761517485

package/Runtime/Unity/Integrations/Reflex/ReflexRegistrationInstaller.cs

@@ -2,7 +2,9 @@
 namespace DxMessaging.Unity.Integrations.Reflex
 {
 #if REFLEX_PRESENT
+    using System;
     using Core.MessageBus;
+    using Core.Pooling;
     using global::Reflex.Attributes;
     using global::Reflex.Core;
 
@@ -87,6 +89,77 @@ namespace DxMessaging.Unity.Integrations.Reflex
             }
         }
     }
+
+    /// <summary>
+    /// Provides convenience helpers for wiring a <see cref="MessageBus"/> into Reflex containers.
+    /// Reflex's container builder defaults to public-only constructor scanning, so today the
+    /// bare <c>Bind&lt;MessageBus&gt;().AsSingleton()</c> pattern resolves through the public
+    /// parameterless constructor. This is fragile against future Reflex versions that broaden
+    /// scanning to non-public constructors -- always prefer the helper below for clarity and
+    /// forward compatibility.
+    /// </summary>
+    public static class ReflexRegistrationExtensions
+    {
+        /// <summary>
+        /// Registers a singleton <see cref="MessageBus"/> exposed as <see cref="IMessageBus"/>
+        /// using an explicit factory.
+        /// </summary>
+        /// <param name="builder">Container builder receiving the registration.</param>
+        public static void AddDxMessagingBus(this ContainerBuilder builder)
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+            builder.AddSingleton(_ => new MessageBus(), typeof(MessageBus), typeof(IMessageBus));
+        }
+
+        /// <summary>
+        /// Registers a singleton <see cref="MessageBus"/> exposed as <see cref="IMessageBus"/>
+        /// using the supplied factory. Allows callers to inject a custom
+        /// <see cref="IDxMessagingClock"/> via <see cref="MessageBus.CreateForInternalUse"/>.
+        /// </summary>
+        /// <param name="builder">Container builder receiving the registration.</param>
+        /// <param name="factory">Delegate that constructs the <see cref="MessageBus"/> instance using the resolver.</param>
+        public static void AddDxMessagingBus(
+            this ContainerBuilder builder,
+            Func<Container, MessageBus> factory
+        )
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+            if (factory == null)
+            {
+                throw new ArgumentNullException(nameof(factory));
+            }
+            builder.AddSingleton(factory, typeof(MessageBus), typeof(IMessageBus));
+        }
+
+        /// <summary>
+        /// Registers a singleton <see cref="MessageBus"/> exposed as <see cref="IMessageBus"/>
+        /// using the supplied <see cref="IDxMessagingClock"/>.
+        /// </summary>
+        /// <param name="builder">Container builder receiving the registration.</param>
+        /// <param name="clock">Clock implementation injected into the bus. Must not be null.</param>
+        public static void AddDxMessagingBus(this ContainerBuilder builder, IDxMessagingClock clock)
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+            if (clock == null)
+            {
+                throw new ArgumentNullException(nameof(clock));
+            }
+            builder.AddSingleton(
+                _ => MessageBus.CreateForInternalUse(clock),
+                typeof(MessageBus),
+                typeof(IMessageBus)
+            );
+        }
+    }
 #endif
 }
 #endif