Skip to content

Subscription ownership

Added in 4.0.0. Use registration groups, source retargeting, and explicit state handlers with an existing token.

A token owns its registrations for its whole lifecycle. A registration group owns a selected subset of those handles. For readiness and current settings, sticky messages let a callback receive the latest explicitly published state when its token activates. Register once during setup. Use a group when a pooled object changes parent or replaces one set of subscriptions while keeping its other subscriptions.

Existing application code API to use
Store handles in a list and remove each handle when the parent changes Enroll each handle with group.Add(...), then call group.Dispose()
Remove a source-bound handle and register its callback again Call token.RetargetSource(handle, newSource)
Capture an owner or local value in a registration lambda Pass the state explicitly and use a static callback

Keep a selected set together

Call token.CreateGroup() and enroll the handles returned by the token. Enrollment does not enable the token. The token's existing owner still calls Enable, Disable, or its lifecycle helper. Disposing a group removes its members from both active subscriptions and future token replays. It leaves the token's other registrations active.

This complete example replaces a parent's subscriptions, retains their cleanup owner before registration starts, and uses static callbacks with explicit state:

C#
namespace SubscriptionOwnershipExample
{
    using System;
    using DxMessaging.Core;
    using DxMessaging.Core.Messages;

    public sealed class ParentSubscriptions : IDisposable
    {
        private readonly MessageRegistrationToken _token;
        private MessageRegistrationGroup _parentGroup;
        private MessageRegistrationHandle _changed;
        private bool _binding;
        private bool _disposing;
        private bool _disposeRequested;

        public int Revision { get; private set; }
        public int HiddenCount { get; private set; }

        /// <summary>Uses an existing token while its lifecycle remains with its original owner.</summary>
        public ParentSubscriptions(MessageRegistrationToken token)
        {
            _token = token ?? throw new ArgumentNullException(nameof(token));
        }

        /// <summary>Replaces parent subscriptions and defers disposal until enrollment finishes.</summary>
        public void BindParent(InstanceId parent)
        {
            if (_binding || _disposing)
            {
                throw new InvalidOperationException("Finish the current parent binding or disposal first.");
            }
            _binding = true;
            try
            {
                DisposeParentGroup();
                _parentGroup = _token.CreateGroup();
                _changed = _parentGroup.Add(
                    _token.RegisterBroadcast<ParentChanged, ParentSubscriptions>(
                        parent, this,
                        static (ParentSubscriptions owner, in ParentChanged message) =>
                            owner.Revision = message.Revision));
                _parentGroup.Add(
                    _token.RegisterBroadcast<ParentHidden, ParentSubscriptions>(
                        parent, this,
                        static (ParentSubscriptions owner, in ParentHidden message) =>
                            ++owner.HiddenCount));
            }
            finally
            {
                _binding = false;
                if (_disposeRequested)
                {
                    _disposeRequested = false;
                    Dispose();
                }
            }
        }

        /// <summary>Moves only the changed-message subscription.</summary>
        public bool MoveChangedHandler(InstanceId source)
        {
            return _token.RetargetSource(_changed, source);
        }

        /// <summary>Removes parent subscriptions after any current enrollment finishes.</summary>
        public void Dispose()
        {
            if (_binding)
            {
                _disposeRequested = true;
                return;
            }
            if (_disposing)
            {
                return;
            }
            _disposing = true;
            try
            {
                DisposeParentGroup();
            }
            finally
            {
                _disposing = false;
            }
        }

        /// <summary>Keeps the owning group reachable until every cleanup obligation completes.</summary>
        private void DisposeParentGroup()
        {
            if (_parentGroup == null)
            {
                return;
            }
            _parentGroup.Dispose();
            if (_parentGroup.Count != 0)
            {
                throw new InvalidOperationException(
                    "Parent cleanup is still pending. Finish it before binding another parent.");
            }
            _parentGroup = null;
        }
    }

    public readonly struct ParentChanged : IBroadcastMessage
    {
        public readonly int Revision;
        public ParentChanged(int revision) => Revision = revision;
        public Type MessageType => typeof(ParentChanged);
    }

    public readonly struct ParentHidden : IBroadcastMessage
    {
        public Type MessageType => typeof(ParentHidden);
    }
}

During BindParent, a reentrant Dispose waits until returned handles are enrolled. During disposal, nested Dispose calls return so the outer call can finish cleanup and check Count. A nested BindParent call is rejected while binding or disposal is in progress. The group field remains reachable if a later registration or cleanup fails. Call Dispose again after resolving a cleanup failure. Replace the group only after its Count reaches zero. Cleanup visits every member even if another removal throws. One failure is rethrown; multiple failures produce an AggregateException. A reentrant callback can accept cleanup after a disposal pass starts, so a pass can return with a nonzero Count. That includes disposal during a registration callback, before the bus returns its cleanup handle. The next pass removes that retained obligation. Draining the final cleanup clears diagnostics when no staged registrations or other cleanup remain.

Duplicate enrollment has no effect while the handle belongs to the token. A handle can belong to multiple groups; removing it from either group cancels that registration. Other groups then hold a harmless stale handle. A retired handle cannot remove a replacement that reuses its slot. Enrollment rejects foreign or missing handles. Once disposal starts, the group rejects further enrollment, including after a failed pass.

Move one source-bound handle

RetargetSource moves a broadcast handler or post-processor registered for one source. It accepts an InstanceId or a Unity GameObject; InstanceId also converts a Component. The GameObject overload handles null by selecting InstanceId.EmptyId before converting live objects. The sample's MoveChangedHandler moves only its changed-message handle; the hidden-message handle stays with its current source. To replace an entire set, finish group cleanup and build a new group.

The move keeps the handle, callback, explicit state, priority, and diagnostic counts. A disabled registration changes staging only. An active registration moves on its current bus. It joins the end of the new source's equal-priority registration order. An outer dispatch finishes its frozen callbacks with their original diagnostic sources; nested and later emissions observe the new route. Moving to the same source does nothing.

The method returns false for an untargeted, targeted, all-source, stale, foreign, or removed handle. It rejects moving the same registration while a custom bus is still accepting it or while another source move owns it. A later queued registration can change its staged source during token replay.

Failed old-source cleanup leaves the old source and handle retryable. A move during that handle's cleanup is rejected before changing its staged source. If failed cleanup and reentrant replay retain more than one bus binding, finish cleanup through the token, handle, or group before moving the source. Failed new-source activation restores old staging and attempts to register it again. Recovery joins the old source's current equal-priority order; it cannot restore a removed insertion position. If recovery also fails, both failures appear in an AggregateException. Reentrant disable or removal takes precedence over activation. If a callback accepts cleanup after a lifecycle cancellation, finish that cleanup through the token, handle, or group before enabling again.

Change the token's bus during cleanup

Fixed in v4.0.0: Calling Disable() or UnregisterAll() from an old-bus cleanup callback cancels pending activation by the enclosing RetargetMessageBus(..., RebindActive) call. After successful cleanup, a later explicit Enable() uses the selected destination and any retained staging. UnregisterAll() removes staging when cleanup completes. Registrations accepted by a callback's explicit re-enable remain owned on their accepting bus until a later cleanup pass.

If old-bus cleanup throws, the token keeps the previous bus for later activation and preserves failed cleanup for retry. Recovery does not reactivate registrations canceled by the callback. Enabled stays true while any cleanup obligation remains; retry cleanup before enabling again.

If new-bus activation fails, Disable() or UnregisterAll() during rollback cleanup also prevents recovery from reactivating staging. Natural rollback completion restores the previous bus when rollback cleanup callbacks do not cancel activation.

Pass state to a static callback

Explicit-state overloads cover untargeted, targeted, source-bound broadcast, all-target, and all-source handlers and post-processors. Their type arguments are the message type followed by the state type. Scalar callbacks receive (state, in message). All-target and all-source callbacks receive (state, in context, in message).

Struct state is copied when registering and passed by value on each delivery. Changing the original struct or a callback's copy does not change the stored value. Reference state stays shared, including changes made after registration. Null reference state is valid. A null callback throws at registration time, including on a disabled token. Separate registrations retain separate bindings even when they use the same static callback.

Registration allocates a state adapter and delegate. Groups also allocate when created and populated. These APIs do not promise allocation-free registration or source moves. The state adapter adds no managed allocation to steady-state dispatch with diagnostics disabled. Prefer a static method or static lambda so the callback does not capture additional application state. Token replay and bus retargeting reuse the stored state.

See also