Runtime Settings¶

Back to Reference | Memory Reclamation Guide | Runtime Configuration

The DxMessagingRuntimeSettings ScriptableObject controls memory-reclamation policy and pool sizing for DxMessaging. This page is the canonical reference for the asset, its parameters, and the public APIs that consume them.

For tuning guidance and scenario-driven recommendations, see the Memory Reclamation guide.

Overview¶

DxMessagingRuntimeSettings is a ScriptableObject that ships with the package and is loaded once per AppDomain during the first message-bus construction via Resources.Load<DxMessagingRuntimeSettings>("DxMessagingRuntimeSettings"). On a load miss the runtime hands out a defaulted in-memory instance so the package always has a usable settings object. Field changes raise SettingsChanged, which live buses subscribe to so they can re-apply caps without recreation. The asset is hot-reloadable: edits saved to disk while Play mode is running take effect on the next sweep boundary.

In non-Unity builds (where UNITY_2021_3_OR_NEWER is not defined) the provider returns null because ScriptableObject is unavailable. Callers must tolerate a null result outside Unity.

Asset Location¶

The asset must live under any Resources/ folder so that Resources.Load can find it at runtime. The recommended path is:

Assets/Resources/DxMessagingRuntimeSettings.asset

Two creation paths put the asset in place:

• Assets > Create > Wallstop Studios > DxMessaging > Runtime Settings. The asset's [CreateAssetMenu] entry; the asset is created in the currently selected folder. Move it under a Resources/ folder afterwards.
• Assets > Create > Wallstop Studios > DxMessaging > Runtime Settings (in Resources). The editor menu helper that creates Assets/Resources/DxMessagingRuntimeSettings.asset directly, creating the Assets/Resources folder if it does not already exist.

The asset's OnValidate warns when an asset path lies outside a Resources/ folder because Resources.Load would not find it there.

Parameter Reference¶

The Min column reflects the [Min(...)] attribute that the editor enforces on numeric fields. Editor-time OnValidate clamps negative values back to zero before raising SettingsChanged.

Public Constants¶

DxMessagingRuntimeSettings exposes four public const fields so scripts can reference the same defaults the asset ships with:

Reference these constants from test fixtures and bootstrap code rather than duplicating literal values.

Public Diagnostic API¶

These APIs let runtime and test code inspect occupancy and request explicit reclamation. All four are stable public surface.

IMessageBus.OccupiedTypeSlots¶

int OccupiedTypeSlots { get; }

Number of currently occupied per-message-type slots on this bus. Includes scalar handler sinks, context handler sinks (one count per (type, dictionary), not per (type, target)), interceptor type slots, and dirty-empty typed-handler slots. Aggregated on read by walking the per-kind caches; the cost is O(n) in the number of distinct message types known to the bus. Snapshot at region boundaries rather than reading in a tight loop.

IMessageBus.OccupiedTargetSlots¶

int OccupiedTargetSlots { get; }

Number of currently occupied per-context target or source slots on this bus. Counts (type, target) tuples: five distinct message types each with the same target ID counts as 5, not 1. Same aggregation behavior as OccupiedTypeSlots; the cost is O(n) in the number of distinct message types known to the bus.

IMessageBus.Trim¶

TrimResult Trim(bool force = false);

Reclaim empty message slots and pooled collections owned by this bus. When force is true, the call ignores idle-age thresholds and drains shared pools to zero. When force is false, only slots past the configured idle threshold are eligible. The call is a no-op returning default(TrimResult) when EnableTrimApi is false.

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 and editor hosts.

MessageHandler.TrimAll¶

public static IMessageBus.TrimResult TrimAll(bool force = false);

Convenience wrapper that calls Trim on the global message bus. Same force semantics as IMessageBus.Trim.

IMessageBus.TrimResult¶

public readonly struct TrimResult : IEquatable<TrimResult>
{
    public int TypeSlotsEvicted { get; }
    public int TargetSlotsEvicted { get; }
    public int PooledCollectionsEvicted { get; }
    public int LiveTypeSlotsRemaining { get; }
}

The struct overrides ToString() and implements equality on all four fields.

Hot-Reload Semantics¶

DxMessagingRuntimeSettings raises the static event DxMessagingRuntimeSettings.SettingsChanged from its editor OnValidate and from DxMessagingRuntimeSettingsProvider.Override. Subscribers should be small and re-entrancy-safe; the event is invoked synchronously on the calling thread.

public static event Action<DxMessagingRuntimeSettings> SettingsChanged;

Existing buses subscribe to the event and call ApplyRuntimeSettings, which re-applies the eviction toggles, idle threshold, tick interval, pool caps, retention mode, and message buffer size without recreating the bus. The shared DxPools pools and the bus-owned context-dictionary pool reapply the new caps on the next reclaim opportunity. Live registrations are not disturbed.

The RuntimeInitializeOnLoadMethod(SubsystemRegistration) hook clears SettingsChanged subscribers when a new domain loads, preventing stale subscriptions from previous Play mode sessions from firing.

Test Override¶

DxMessagingRuntimeSettingsProvider.Override(DxMessagingRuntimeSettings settings) pushes a test-supplied settings instance as the active Current value and returns an IDisposable. Disposing the token restores the previous instance (LIFO; if a deeper override was pushed on top, dispose is a no-op until the deeper override is popped first). Both the push and the pop raise SettingsChanged so subscribed buses re-apply caps in both directions.

using System;
using DxMessaging.Core.Configuration;
using UnityEngine;

public static class TestSettingsExample
{
    public static void RunWithCustomSettings()
    {
        DxMessagingRuntimeSettings testSettings =
            ScriptableObject.CreateInstance<DxMessagingRuntimeSettings>();
        // Test-only: production code should not call Override directly.
        using (IDisposable token =
            DxMessagingRuntimeSettingsProvider.Override(testSettings))
        {
            // Bus reads testSettings until token is disposed.
        }
    }
}

The provider is intended for tests and bootstrap code that needs to inject a specific configuration. Production code should rely on the loaded asset (or the defaulted fallback) rather than calling Override directly.

See Also¶

• Memory Reclamation guide
• Runtime Configuration
• Diagnostics
• Performance