Package com.google.common.util.concurrent

Class ListenerCallQueue<L>

  • final class ListenerCallQueue<L>
extends java.lang.Object
    A list of listeners for implementing a concurrency friendly observable object.

    Listeners are registered once via addListener(L, java.util.concurrent.Executor) and then may be invoked by enqueueing and then dispatching events.

    The API of this class is designed to make it easy to achieve the following properties

    • Multiple events for the same listener are never dispatched concurrently.
    • Events for the different listeners are dispatched concurrently.
    • All events for a given listener dispatch on the provided #executor.
    • It is easy for the user to ensure that listeners are never invoked while holding locks.
    The last point is subtle. Often the observable object will be managing its own internal state using a lock, however it is dangerous to dispatch listeners while holding a lock because they might run on the directExecutor() or be otherwise re-entrant (call back into your object). So it is important to not call dispatch() while holding any locks. This is why enqueue(com.google.common.util.concurrent.ListenerCallQueue.Event<L>) and dispatch() are 2 different methods. It is expected that the decision to run a particular event is made during the state change, but the decision to actually invoke the listeners can be delayed slightly so that locks can be dropped. Also, because dispatch() is expected to be called concurrently, it is idempotent.

    • Constructor Detail

      • ListenerCallQueue

        ListenerCallQueue()

    • Method Detail

      • addListener

        public void addListener​(L listener,
                        java.util.concurrent.Executor executor)
        Adds a listener that will be called using the given executor when events are later enqueued and dispatched.

      • enqueue

        public void enqueue​(ListenerCallQueue.Event<L> event)
        Enqueues an event to be run on currently known listeners.

        The toString method of the Event itself will be used to describe the event in the case of an error.

        Parameters:
        event - the callback to execute on dispatch()

      • enqueue

        public void enqueue​(ListenerCallQueue.Event<L> event,
                    java.lang.String label)
        Enqueues an event to be run on currently known listeners, with a label.
        Parameters:
        event - the callback to execute on dispatch()
        label - a description of the event to use in the case of an error

      • dispatch

        public void dispatch()
        Dispatches all events enqueued prior to this call, serially and in order, for every listener.

        Note: this method is idempotent and safe to call from any thread