Class ListenerCallQueue<L>

java.lang.Object
com.google.common.util.concurrent.ListenerCallQueue<L>

final class ListenerCallQueue<L> extends 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
    invalid reference
    #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.
  • Field Details

  • Constructor Details

    • ListenerCallQueue

      ListenerCallQueue()
  • Method Details

    • addListener

      public void addListener(L listener, 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, 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
    • enqueueHelper

      private void enqueueHelper(ListenerCallQueue.Event<L> event, Object label)
    • 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