Class ListenerCallQueue<L>
- java.lang.Object
-
- com.google.common.util.concurrent.ListenerCallQueue<L>
-
@GwtIncompatible 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.
directExecutor()
or be otherwise re-entrant (call back into your object). So it is important to not calldispatch()
while holding any locks. This is whyenqueue(com.google.common.util.concurrent.ListenerCallQueue.Event<L>)
anddispatch()
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, becausedispatch()
is expected to be called concurrently, it is idempotent.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) static interface
ListenerCallQueue.Event<L>
Method reference-compatible listener event.private static class
ListenerCallQueue.PerListenerQueue<L>
A special purpose queue/executor that dispatches listener events serially on a configured executor.
-
Field Summary
Fields Modifier and Type Field Description private java.util.List<ListenerCallQueue.PerListenerQueue<L>>
listeners
private static java.util.logging.Logger
logger
-
Constructor Summary
Constructors Constructor Description ListenerCallQueue()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addListener(L listener, java.util.concurrent.Executor executor)
Adds a listener that will be called using the given executor when events are laterenqueued
anddispatched
.void
dispatch()
Dispatches all events enqueued prior to this call, serially and in order, for every listener.void
enqueue(ListenerCallQueue.Event<L> event)
Enqueues an event to be run on currently known listeners.void
enqueue(ListenerCallQueue.Event<L> event, java.lang.String label)
Enqueues an event to be run on currently known listeners, with a label.private void
enqueueHelper(ListenerCallQueue.Event<L> event, java.lang.Object label)
-
-
-
Field Detail
-
logger
private static final java.util.logging.Logger logger
-
listeners
private final java.util.List<ListenerCallQueue.PerListenerQueue<L>> listeners
-
-
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 laterenqueued
anddispatched
.
-
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 ondispatch()
-
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 ondispatch()
label
- a description of the event to use in the case of an error
-
enqueueHelper
private void enqueueHelper(ListenerCallQueue.Event<L> event, java.lang.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
-
-