android-15.0.0_r3/s

/*
 * Copyright (C) 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.android.server.location.listeners;

import android.annotation.NonNull;
import android.annotation.Nullable;
import android.util.ArrayMap;
import android.util.ArraySet;

import com.android.internal.annotations.GuardedBy;
import com.android.internal.listeners.ListenerExecutor.ListenerOperation;
import com.android.internal.util.Preconditions;

import java.io.FileDescriptor;
import java.io.PrintWriter;
import java.util.AbstractMap;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Map.Entry;
import java.util.Objects;
import java.util.function.Function;
import java.util.function.Predicate;

/**
 * A base class to multiplex some event source to multiple listener registrations. Every listener is
 * represented by a registration object which stores all required state for a listener. Keys are
 * used to uniquely identify every registration. Listener operations may be executed on
 * registrations in order to invoke the represented listener.
 *
 * <p>Registrations are divided into two categories, active registrations and inactive
 * registrations, as defined by {@link #isActive(ListenerRegistration)}. The set of active
 * registrations is combined into a single merged registration, which is submitted to the backing
 * event source when necessary in order to register with the event source. The merged registration
 * is updated whenever the set of active registration changes. Listeners will only be invoked for
 * active registrations.
 *
 * <p>In order to inform the multiplexer of state changes, if a registration's active state changes,
 * or if the merged registration changes, {@link #updateRegistrations(Predicate)} or {@link
 * #updateRegistration(Object, Predicate)} must be invoked and return true for any registration
 * whose state may have changed in such a way that the active state or merged registration state has
 * changed. It is acceptable to return true from a predicate even if nothing has changed, though
 * this may result in extra pointless work.
 *
 * <p>Callbacks invoked for various changes will always be ordered according to this lifecycle list:
 *
 * <ul>
 *   <li>{@link #onRegister()}
 *   <li>{@link ListenerRegistration#onRegister(Object)}
 *   <li>{@link #onRegistrationAdded(Object, ListenerRegistration)}
 *   <li>{@link #onActive()}
 *   <li>{@link ListenerRegistration#onActive()}
 *   <li>{@link ListenerRegistration#onInactive()}
 *   <li>{@link #onInactive()}
 *   <li>{@link #onRegistrationRemoved(Object, ListenerRegistration)}
 *   <li>{@link ListenerRegistration#onUnregister()}
 *   <li>{@link #onUnregister()}
 * </ul>
 *
 * <p>If one registration replaces another, then {@link #onRegistrationReplaced(Object,
 * ListenerRegistration, Object, ListenerRegistration)} is invoked instead of {@link
 * #onRegistrationRemoved(Object, ListenerRegistration)} and {@link #onRegistrationAdded(Object,
 * ListenerRegistration)}.
 *
 * <p>Adding registrations is not allowed to be called re-entrantly (ie, while in the middle of some
 * other operation or callback). Removal is allowed re-entrantly, however only via {@link
 * #removeRegistration(Object, ListenerRegistration)}, not via any other removal method. This
 * ensures re-entrant removal does not accidentally remove the incorrect registration.
 *
 * @param <TKey>                key type
 * @param <TListener>           listener type
 * @param <TRegistration>       registration type
 * @param <TMergedRegistration> merged registration type
 */
public abstract class ListenerMultiplexer<TKey, TListener,
        TRegistration extends ListenerRegistration<TListener>, TMergedRegistration> {

    /**
     * The lock object used by the multiplexer. Acquiring this lock allows for multiple operations
     * on the multiplexer to be completed atomically. Otherwise, it is not required to hold this
     * lock. This lock is held while invoking all lifecycle callbacks on both the multiplexer and
     * any registrations.
     */
    protected final Object mMultiplexerLock = new Object();

    @GuardedBy("mMultiplexerLock")
    private final ArrayMap<TKey, TRegistration> mRegistrations = new ArrayMap<>();

    private final UpdateServiceBuffer mUpdateServiceBuffer = new UpdateServiceBuffer();

    private final ReentrancyGuard mReentrancyGuard = new ReentrancyGuard();

    @GuardedBy("mMultiplexerLock")
    private int mActiveRegistrationsCount = 0;

    @GuardedBy("mMultiplexerLock")
    private boolean mServiceRegistered = false;

    @GuardedBy("mMultiplexerLock")
    @Nullable private TMergedRegistration mMerged;

    /**
     * Should be implemented to register with the backing service with the given merged
     * registration, and should return true if a matching call to {@link #unregisterWithService()}
     * is required to unregister (ie, if registration succeeds). The set of registrations passed in
     * is the same set passed into {@link #mergeRegistrations(Collection)} to generate the merged
     * registration.
     *
     * <p class="note">It may seem redundant to pass in the set of active registrations when they
     * have already been used to generate the merged request, and indeed, for many implementations
     * this parameter can likely simply be ignored. However, some implementations may require access
     * to the set of registrations used to generate the merged requestion for further logic even
     * after the merged registration has been generated.
     *
     * @see #mergeRegistrations(Collection)
     * @see #reregisterWithService(Object, Object, Collection)
     */
    @GuardedBy("mMultiplexerLock")
    protected abstract boolean registerWithService(TMergedRegistration merged,
            @NonNull Collection<TRegistration> registrations);

    /**
     * Invoked when the service has already been registered with some merged registration, and is
     * now being registered with a different merged registration. The default implementation simply
     * invokes {@link #registerWithService(Object, Collection)}.
     *
     * @see #registerWithService(Object, Collection)
     */
    @GuardedBy("mMultiplexerLock")
    protected boolean reregisterWithService(TMergedRegistration oldMerged,
            TMergedRegistration newMerged, @NonNull Collection<TRegistration> registrations) {
        return registerWithService(newMerged, registrations);
    }

    /**
     * Should be implemented to unregister from the backing service.
     */
    @GuardedBy("mMultiplexerLock")
    protected abstract void unregisterWithService();

    /**
     * Defines whether a registration is currently active or not. Only active registrations will be
     * forwarded to {@link #registerWithService(Object, Collection)}, and listener invocations will
     * only be delivered to active requests. If a registration's active state changes,
     * {@link #updateRegistrations(Predicate)} must be invoked with a function that returns true for
     * any registrations that may have changed their active state.
     */
    @GuardedBy("mMultiplexerLock")
    protected abstract boolean isActive(@NonNull TRegistration registration);

    /**
     * Called in order to generate a merged registration from the given set of active registrations.
     * The list of registrations will never be empty. If the resulting merged registration is equal
     * to the currently registered merged registration, nothing further will happen. If the merged
     * registration differs, {@link #registerWithService(Object, Collection)} or
     * {@link #reregisterWithService(Object, Object, Collection)} will be invoked with the new
     * merged registration so that the backing service can be updated.
     */
    @GuardedBy("mMultiplexerLock")
    protected abstract TMergedRegistration mergeRegistrations(
            @NonNull Collection<TRegistration> registrations);

    /**
     * Invoked when the multiplexer goes from having no registrations to having some registrations.
     * This is a convenient entry point for registering listeners, etc, which only need to be
     * present while there are any registrations. Invoked while holding the multiplexer's internal
     * lock.
     */
    @GuardedBy("mMultiplexerLock")
    protected void onRegister() {}

    /**
     * Invoked when the multiplexer goes from having some registrations to having no registrations.
     * This is a convenient entry point for unregistering listeners, etc, which only need to be
     * present while there are any registrations. Invoked while holding the multiplexer's internal
     * lock.
     */
    @GuardedBy("mMultiplexerLock")
    protected void onUnregister() {}

    /**
     * Invoked when a registration is added. Invoked while holding the multiplexer's internal lock.
     */
    @GuardedBy("mMultiplexerLock")
    protected void onRegistrationAdded(@NonNull TKey key, @NonNull TRegistration registration) {}

    /**
     * Invoked when one registration replaces another (through {@link #replaceRegistration(Object,
     * Object, ListenerRegistration)}). The old registration has already been unregistered at this
     * point. Invoked while holding the multiplexer's internal lock.
     *
     * <p>The default behavior is simply to call first {@link #onRegistrationRemoved(Object,
     * ListenerRegistration)} and then {@link #onRegistrationAdded(Object, ListenerRegistration)}.
     */
    @GuardedBy("mMultiplexerLock")
    protected void onRegistrationReplaced(
            @NonNull TKey oldKey,
            @NonNull TRegistration oldRegistration,
            @NonNull TKey newKey,
            @NonNull TRegistration newRegistration) {
        onRegistrationRemoved(oldKey, oldRegistration);
        onRegistrationAdded(newKey, newRegistration);
    }

    /**
     * Invoked when a registration is removed. Invoked while holding the multiplexer's internal
     * lock.
     */
    @GuardedBy("mMultiplexerLock")
    protected void onRegistrationRemoved(@NonNull TKey key, @NonNull TRegistration registration) {}

    /**
     * Invoked when the multiplexer goes from having no active registrations to having some active
     * registrations. This is a convenient entry point for registering listeners, etc, which only
     * need to be present while there are active registrations. Invoked while holding the
     * multiplexer's internal lock.
     */
    @GuardedBy("mMultiplexerLock")
    protected void onActive() {}

    /**
     * Invoked when the multiplexer goes from having some active registrations to having no active
     * registrations. This is a convenient entry point for unregistering listeners, etc, which only
     * need to be present while there are active registrations. Invoked while holding the
     * multiplexer's internal lock.
     */
    @GuardedBy("mMultiplexerLock")
    protected void onInactive() {}

    /**
     * Puts a new registration with the given key, replacing any previous registration under the
     * same key. This method cannot be called to put a registration re-entrantly.
     */
    protected final void putRegistration(@NonNull TKey key, @NonNull TRegistration registration) {
        replaceRegistration(key, key, registration);
    }

    /**
     * Atomically removes the registration with the old key and adds a new registration with the
     * given key. If there was a registration for the old key, {@link
     * #onRegistrationReplaced(Object, ListenerRegistration, Object, ListenerRegistration)} will be
     * invoked instead of {@link #onRegistrationAdded(Object, ListenerRegistration)}, even if they
     * share the same key. The old key may be the same value as the new key, in which case this
     * function is equivalent to {@link #putRegistration(Object, ListenerRegistration)}. This method
     * cannot be called to add a registration re-entrantly.
     */
    protected final void replaceRegistration(@NonNull TKey oldKey, @NonNull TKey key,
            @NonNull TRegistration registration) {
        Objects.requireNonNull(oldKey);
        Objects.requireNonNull(key);
        Objects.requireNonNull(registration);

        synchronized (mMultiplexerLock) {
            // adding listeners reentrantly is not supported
            Preconditions.checkState(!mReentrancyGuard.isReentrant());

            // new key may only have a prior registration if the oldKey is the same as the key
            Preconditions.checkArgument(oldKey == key || !mRegistrations.containsKey(key));

            // since adding a registration can invoke a variety of callbacks, we need to ensure
            // those callbacks themselves do not re-enter, as this could lead to out-of-order
            // callbacks. further, we buffer service updates since adding a registration may
            // involve removing a prior registration. note that try-with-resources ordering is
            // meaningful here as well. we want to close the reentrancy guard first, as this may
            // generate additional service updates, then close the update service buffer.
            try (UpdateServiceBuffer ignored1 = mUpdateServiceBuffer.acquire();
                 ReentrancyGuard ignored2 = mReentrancyGuard.acquire()) {

                boolean wasEmpty = mRegistrations.isEmpty();

                TRegistration oldRegistration = null;
                int oldIndex = mRegistrations.indexOfKey(oldKey);
                if (oldIndex >= 0) {
                    // remove ourselves instead of using remove(), to balance registration callbacks
                    oldRegistration = mRegistrations.valueAt(oldIndex);
                    unregister(oldRegistration);
                    oldRegistration.onUnregister();
                    if (oldKey != key) {
                        mRegistrations.removeAt(oldIndex);
                    }
                }
                if (oldKey == key && oldIndex >= 0) {
                    mRegistrations.setValueAt(oldIndex, registration);
                } else {
                    mRegistrations.put(key, registration);
                }

                if (wasEmpty) {
                    onRegister();
                }
                registration.onRegister(key);
                if (oldRegistration == null) {
                    onRegistrationAdded(key, registration);
                } else {
                    onRegistrationReplaced(oldKey, oldRegistration, key, registration);
                }
                onRegistrationActiveChanged(registration);
            }
        }
    }

    /**
     * Removes all registrations with keys that satisfy the given predicate. This method cannot be
     * called to remove a registration re-entrantly.
     */
    protected final void removeRegistrationIf(@NonNull Predicate<TKey> predicate) {
        synchronized (mMultiplexerLock) {
            // this method does not support removing listeners reentrantly
            Preconditions.checkState(!mReentrancyGuard.isReentrant());

            // since removing a registration can invoke a variety of callbacks, we need to ensure
            // those callbacks themselves do not re-enter, as this could lead to out-of-order
            // callbacks. further, we buffer service updates since chains of removeLater()
            // invocations could result in multiple service updates. note that try-with-resources
            // ordering is meaningful here as well. we want to close the reentrancy guard first, as
            // this may generate additional service updates, then close the update service buffer.
            try (UpdateServiceBuffer ignored1 = mUpdateServiceBuffer.acquire();
                 ReentrancyGuard ignored2 = mReentrancyGuard.acquire()) {

                final int size = mRegistrations.size();
                for (int i = 0; i < size; i++) {
                    TKey key = mRegistrations.keyAt(i);
                    if (predicate.test(key)) {
                        removeRegistration(key, mRegistrations.valueAt(i));
                    }
                }
            }
        }
    }

    /**
     * Removes the registration with the given key. This method cannot be called to remove a
     * registration re-entrantly.
     */
    protected final void removeRegistration(TKey key) {
        synchronized (mMultiplexerLock) {
            // this method does not support removing listeners reentrantly
            Preconditions.checkState(!mReentrancyGuard.isReentrant());

            int index = mRegistrations.indexOfKey(key);
            if (index < 0) {
                return;
            }

            removeRegistration(index);
        }
    }

    /**
     * Removes the given registration with the given key. If the given key has a different
     * registration at the time this method is called, nothing happens. This method allows for
     * re-entrancy, and may be called to remove a registration re-entrantly.
     */
    protected final void removeRegistration(@NonNull TKey key,
            @NonNull ListenerRegistration<?> registration) {
        synchronized (mMultiplexerLock) {
            int index = mRegistrations.indexOfKey(key);
            if (index < 0) {
                return;
            }

            TRegistration typedRegistration = mRegistrations.valueAt(index);
            if (typedRegistration != registration) {
                return;
            }

            if (mReentrancyGuard.isReentrant()) {
                unregister(typedRegistration);
                mReentrancyGuard.markForRemoval(key, typedRegistration);
            } else {
                removeRegistration(index);
            }
        }
    }

    @GuardedBy("mMultiplexerLock")
    private void removeRegistration(int index) {
        TKey key = mRegistrations.keyAt(index);
        TRegistration registration = mRegistrations.valueAt(index);

        // since removing a registration can invoke a variety of callbacks, we need to ensure those
        // callbacks themselves do not re-enter, as this could lead to out-of-order callbacks.
        // further, we buffer service updates since chains of removeLater() invocations could result
        // in multiple service updates. note that try-with-resources ordering is meaningful here as
        // well. we want to close the reentrancy guard first, as this may generate additional
        // service updates, then close the update service buffer.
        try (UpdateServiceBuffer ignored1 = mUpdateServiceBuffer.acquire();
             ReentrancyGuard ignored2 = mReentrancyGuard.acquire()) {

            unregister(registration);
            onRegistrationRemoved(key, registration);
            registration.onUnregister();
            mRegistrations.removeAt(index);
            if (mRegistrations.isEmpty()) {
                onUnregister();
            }
        }
    }

    /**
     * Forces a re-evalution of the merged request for all active registrations and updates service
     * registration accordingly.
     */
    protected final void updateService() {
        synchronized (mMultiplexerLock) {
            if (mUpdateServiceBuffer.isBuffered()) {
                mUpdateServiceBuffer.markUpdateServiceRequired();
                return;
            }

            final int size = mRegistrations.size();
            ArrayList<TRegistration> actives = new ArrayList<>(size);
            for (int i = 0; i < size; i++) {
                TRegistration registration = mRegistrations.valueAt(i);
                if (registration.isActive()) {
                    actives.add(registration);
                }
            }

            if (actives.isEmpty()) {
                if (mServiceRegistered) {
                    mMerged = null;
                    mServiceRegistered = false;
                    unregisterWithService();
                }
            } else {
                TMergedRegistration merged = mergeRegistrations(actives);
                if (mServiceRegistered) {
                    if (!Objects.equals(merged, mMerged)) {
                        mServiceRegistered = reregisterWithService(mMerged, merged, actives);
                        mMerged = mServiceRegistered ? merged : null;
                    }
                } else {
                    mServiceRegistered = registerWithService(merged, actives);
                    mMerged = mServiceRegistered ? merged : null;
                }
            }
        }
    }

    /**
     * If the service is currently registered, unregisters it and then calls
     * {@link #updateService()} so that {@link #registerWithService(Object, Collection)} will be
     * re-invoked. This is useful, for instance, if the backing service has crashed or otherwise
     * lost state, and needs to be re-initialized. Because this unregisters first, this is safe to
     * use even if there is a possibility the backing server has not crashed, or has already been
     * reinitialized.
     */
    protected final void resetService() {
        synchronized (mMultiplexerLock) {
            if (mServiceRegistered) {
                mMerged = null;
                mServiceRegistered = false;
                unregisterWithService();
                updateService();
            }
        }
    }

    /**
     * Begins buffering calls to {@link #updateService()} until {@link UpdateServiceLock#close()}
     * is called. This is useful to prevent extra work when combining multiple calls (for example,
     * buffering {@code updateService()} until after multiple adds/removes/updates occur.
     */
    public UpdateServiceLock newUpdateServiceLock() {
        return new UpdateServiceLock(mUpdateServiceBuffer);
    }

    /**
     * Evaluates the predicate on all registrations until the predicate returns true, at which point
     * evaluation will cease. Returns true if the predicate ever returned true, and returns false
     * otherwise.
     */
    protected final boolean findRegistration(Predicate<TRegistration> predicate) {
        synchronized (mMultiplexerLock) {
            // we only acquire a reentrancy guard in case of removal while iterating. this method
            // does not directly affect active state or merged state, so there is no advantage to
            // acquiring an update source buffer.
            try (ReentrancyGuard ignored = mReentrancyGuard.acquire()) {
                final int size = mRegistrations.size();
                for (int i = 0; i < size; i++) {
                    TRegistration registration = mRegistrations.valueAt(i);
                    if (predicate.test(registration)) {
                        return true;
                    }
                }
            }

            return false;
        }
    }

    /**
     * Evaluates the predicate on all registrations. The predicate should return true if the active
     * state of the registration may have changed as a result. If the active state of any
     * registration has changed, {@link #updateService()} will automatically be invoked to handle
     * the resulting changes.
     */
    protected final void updateRegistrations(@NonNull Predicate<TRegistration> predicate) {
        synchronized (mMultiplexerLock) {
            // since updating a registration can invoke a variety of callbacks, we need to ensure
            // those callbacks themselves do not re-enter, as this could lead to out-of-order
            // callbacks. note that try-with-resources ordering is meaningful here as well. we want
            // to close the reentrancy guard first, as this may generate additional service updates,
            // then close the update service buffer.
            try (UpdateServiceBuffer ignored1 = mUpdateServiceBuffer.acquire();
                 ReentrancyGuard ignored2 = mReentrancyGuard.acquire()) {

                final int size = mRegistrations.size();
                for (int i = 0; i < size; i++) {
                    TRegistration registration = mRegistrations.valueAt(i);
                    if (predicate.test(registration)) {
                        onRegistrationActiveChanged(registration);
                    }
                }
            }
        }
    }

    /**
     * Evaluates the predicate on a registration with the given key. The predicate should return
     * true if the active state of the registration may have changed as a result. If the active
     * state of the registration has changed, {@link #updateService()} will automatically be invoked
     * to handle the resulting changes. Returns true if there is a registration with the given key
     * (and thus the predicate was invoked), and false otherwise.
     */
    protected final boolean updateRegistration(@NonNull Object key,
            @NonNull Predicate<TRegistration> predicate) {
        synchronized (mMultiplexerLock) {
            // since updating a registration can invoke a variety of callbacks, we need to ensure
            // those callbacks themselves do not re-enter, as this could lead to out-of-order
            // callbacks. note that try-with-resources ordering is meaningful here as well. we want
            // to close the reentrancy guard first, as this may generate additional service updates,
            // then close the update service buffer.
            try (UpdateServiceBuffer ignored1 = mUpdateServiceBuffer.acquire();
                 ReentrancyGuard ignored2 = mReentrancyGuard.acquire()) {

                int index = mRegistrations.indexOfKey(key);
                if (index < 0) {
                    return false;
                }

                TRegistration registration = mRegistrations.valueAt(index);
                if (predicate.test(registration)) {
                    onRegistrationActiveChanged(registration);
                }
                return true;
            }
        }
    }

    @GuardedBy("mMultiplexerLock")
    private void onRegistrationActiveChanged(TRegistration registration) {
        boolean active = registration.isRegistered() && isActive(registration);
        boolean changed = registration.setActive(active);
        if (changed) {
            if (active) {
                if (++mActiveRegistrationsCount == 1) {
                    onActive();
                }
                registration.onActive();
            } else {
                registration.onInactive();
                if (--mActiveRegistrationsCount == 0) {
                    onInactive();
                }
            }

            updateService();
        }
    }

    /**
     * Executes the given function for all active registrations. If the function returns a non-null
     * operation, that operation will be invoked with the associated listener. The function may not
     * change the active state of the registration.
     */
    protected final void deliverToListeners(
            @NonNull Function<TRegistration, ListenerOperation<TListener>> function) {
        synchronized (mMultiplexerLock) {
            try (ReentrancyGuard ignored = mReentrancyGuard.acquire()) {
                final int size = mRegistrations.size();
                for (int i = 0; i < size; i++) {
                    TRegistration registration = mRegistrations.valueAt(i);
                    if (registration.isActive()) {
                        ListenerOperation<TListener> operation = function.apply(registration);
                        if (operation != null) {
                            registration.executeOperation(operation);
                        }
                    }
                }
            }
        }
    }

    /**
     * Executes the given operation for all active listeners. This is a convenience function
     * equivalent to:
     * <pre>
     * deliverToListeners(registration -> operation);
     * </pre>
     */
    protected final void deliverToListeners(@NonNull ListenerOperation<TListener> operation) {
        synchronized (mMultiplexerLock) {
            try (ReentrancyGuard ignored = mReentrancyGuard.acquire()) {
                final int size = mRegistrations.size();
                for (int i = 0; i < size; i++) {
                    TRegistration registration = mRegistrations.valueAt(i);
                    if (registration.isActive()) {
                        registration.executeOperation(operation);
                    }
                }
            }
        }
    }

    @GuardedBy("mMultiplexerLock")
    private void unregister(TRegistration registration) {
        registration.unregisterInternal();
        onRegistrationActiveChanged(registration);
    }

    /**
     * Dumps debug information.
     */
    public void dump(FileDescriptor fd, PrintWriter pw, String[] args) {
        synchronized (mMultiplexerLock) {
            pw.print("service: ");
            pw.print(getServiceState());
            pw.println();

            if (!mRegistrations.isEmpty()) {
                pw.println("listeners:");

                final int size = mRegistrations.size();
                for (int i = 0; i < size; i++) {
                    TRegistration registration = mRegistrations.valueAt(i);
                    pw.print("  ");
                    pw.print(registration);
                    if (!registration.isActive()) {
                        pw.println(" (inactive)");
                    } else {
                        pw.println();
                    }
                }
            }
        }
    }

    /**
     * May be overridden to provide additional details on service state when dumping the manager
     * state. Invoked while holding the multiplexer's internal lock.
     */
    @GuardedBy("mMultiplexerLock")
    protected String getServiceState() {
        if (mServiceRegistered) {
            if (mMerged != null) {
                return mMerged.toString();
            } else {
                return "registered";
            }
        } else {
            return "unregistered";
        }
    }

    /**
     * A reference counted helper class that guards against re-entrancy, and also helps implement
     * registration removal during reentrancy. When this class is {@link #acquire()}d, it increments
     * the reference count. To check whether re-entrancy is occurring, clients may use
     * {@link #isReentrant()}, and modify their behavior (such as by failing the call, or calling
     * {@link #markForRemoval(Object, ListenerRegistration)}). When this class is {@link #close()}d,
     * any key/registration pairs that were marked for removal prior to the close operation will
     * then be removed - which is safe since the operation will no longer be re-entrant.
     */
    private final class ReentrancyGuard implements AutoCloseable {

        @GuardedBy("mMultiplexerLock")
        private int mGuardCount;

        @GuardedBy("mMultiplexerLock")
        @Nullable private ArraySet<Entry<TKey, ListenerRegistration<?>>> mScheduledRemovals;

        ReentrancyGuard() {
            mGuardCount = 0;
            mScheduledRemovals = null;
        }

        boolean isReentrant() {
            synchronized (mMultiplexerLock) {
                return mGuardCount != 0;
            }
        }

        void markForRemoval(TKey key, ListenerRegistration<?> registration) {
            synchronized (mMultiplexerLock) {
                Preconditions.checkState(isReentrant());

                if (mScheduledRemovals == null) {
                    mScheduledRemovals = new ArraySet<>(mRegistrations.size());
                }
                mScheduledRemovals.add(new AbstractMap.SimpleImmutableEntry<>(key, registration));
            }
        }

        ReentrancyGuard acquire() {
            synchronized (mMultiplexerLock) {
                ++mGuardCount;
                return this;
            }
        }

        @Override
        public void close() {
            synchronized (mMultiplexerLock) {
                Preconditions.checkState(mGuardCount > 0);

                ArraySet<Entry<TKey, ListenerRegistration<?>>> scheduledRemovals = null;

                if (--mGuardCount == 0) {
                    scheduledRemovals = mScheduledRemovals;
                    mScheduledRemovals = null;
                }

                if (scheduledRemovals == null) {
                    return;
                }

                try (UpdateServiceBuffer ignored = mUpdateServiceBuffer.acquire()) {
                    final int size = scheduledRemovals.size();
                    for (int i = 0; i < size; i++) {
                        Entry<TKey, ListenerRegistration<?>> entry = scheduledRemovals.valueAt(i);
                        removeRegistration(entry.getKey(), entry.getValue());
                    }
                }
            }
        }
    }

    /**
     * A reference counted helper class that buffers class to {@link #updateService()}. Since
     * {@link #updateService()} iterates through every registration and performs request merging
     * work, it can often be the most expensive part of any update to the multiplexer. This means
     * that if multiple calls to updateService() can be buffered, work will be saved. This class
     * allows clients to begin buffering calls after {@link #acquire()}ing this class, and when
     * {@link #close()} is called, any buffered calls to {@link #updateService()} will be combined
     * into a single final call. Clients should acquire this class when they are doing work that
     * could potentially result in multiple calls to updateService(), and close when they are done
     * with that work.
     */
    private final class UpdateServiceBuffer implements AutoCloseable {

        // requires internal locking because close() may be exposed externally and could be called
        // from any thread

        @GuardedBy("this")
        private int mBufferCount;

        @GuardedBy("this")
        private boolean mUpdateServiceRequired;

        UpdateServiceBuffer() {
            mBufferCount = 0;
            mUpdateServiceRequired = false;
        }

        synchronized boolean isBuffered() {
            return mBufferCount != 0;
        }

        synchronized void markUpdateServiceRequired() {
            Preconditions.checkState(isBuffered());
            mUpdateServiceRequired = true;
        }

        synchronized UpdateServiceBuffer acquire() {
            ++mBufferCount;
            return this;
        }

        @Override
        public void close() {
            boolean updateServiceRequired = false;
            synchronized (this) {
                Preconditions.checkState(mBufferCount > 0);
                if (--mBufferCount == 0) {
                    updateServiceRequired = mUpdateServiceRequired;
                    mUpdateServiceRequired = false;
                }
            }

            if (updateServiceRequired) {
                updateService();
            }
        }
    }

    /**
     * Acquiring this lock will buffer all calls to {@link #updateService()} until the lock is
     * {@link #close()}ed. This can be used to save work by acquiring the lock before multiple calls
     * to updateService() are expected, and closing the lock after.
     */
    public static final class UpdateServiceLock implements AutoCloseable {

        @Nullable private ListenerMultiplexer<?, ?, ?, ?>.UpdateServiceBuffer mUpdateServiceBuffer;

        UpdateServiceLock(ListenerMultiplexer<?, ?, ?, ?>.UpdateServiceBuffer updateServiceBuffer) {
            mUpdateServiceBuffer = updateServiceBuffer.acquire();
        }

        @Override
        public void close() {
            if (mUpdateServiceBuffer != null) {
                ListenerMultiplexer<?, ?, ?, ?>.UpdateServiceBuffer buffer = mUpdateServiceBuffer;
                mUpdateServiceBuffer = null;
                buffer.close();
            }
        }
    }
}