org.openstreetmap.josm.eventbus

Class Dispatcher

java.lang.Object

org.openstreetmap.josm.eventbus.Dispatcher

Direct Known Subclasses:

Dispatcher.ImmediateDispatcher, Dispatcher.LegacyAsyncDispatcher, Dispatcher.PerThreadQueuedDispatcher

abstract class Dispatcher
extends Object

Handler for dispatching events to subscribers, providing different event ordering guarantees that make sense for different situations.

Note: The dispatcher is orthogonal to the subscriber's Executor. The dispatcher controls the order in which events are dispatched, while the executor controls how (i.e. on which thread) the subscriber is actually called when an event is dispatched to it.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	Dispatcher.ImmediateDispatcher Implementation of immediate().
private static class	Dispatcher.LegacyAsyncDispatcher Implementation of a legacyAsync() dispatcher.
private static class	Dispatcher.PerThreadQueuedDispatcher Implementation of a perThreadDispatchQueue() dispatcher.

Constructor Summary

Constructors

Constructor and Description
Dispatcher()

Method Summary

Modifier and Type	Method and Description
(package private) abstract void	dispatch(Object event, Iterator<Subscriber> subscribers) Dispatches the given event to the given subscribers.
(package private) static Dispatcher	immediate() Returns a dispatcher that dispatches events to subscribers immediately as they're posted without using an intermediate queue to change the dispatch order.
(package private) static Dispatcher	legacyAsync() Returns a dispatcher that queues events that are posted in a single global queue.
(package private) static Dispatcher	perThreadDispatchQueue() Returns a dispatcher that queues events that are posted reentrantly on a thread that is already dispatching an event, guaranteeing that all events posted on a single thread are dispatched to all subscribers in the order they are posted.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Dispatcher

Dispatcher()

Method Detail

perThreadDispatchQueue

static Dispatcher perThreadDispatchQueue()

Returns a dispatcher that queues events that are posted reentrantly on a thread that is already dispatching an event, guaranteeing that all events posted on a single thread are dispatched to all subscribers in the order they are posted.

When all subscribers are dispatched to using a direct executor (which dispatches on the same thread that posts the event), this yields a breadth-first dispatch order on each thread. That is, all subscribers to a single event A will be called before any subscribers to any events B and C that are posted to the event bus by the subscribers to A.

Returns:

dispatcher

legacyAsync

static Dispatcher legacyAsync()

Returns a dispatcher that queues events that are posted in a single global queue. This behavior matches the original behavior of AsyncEventBus exactly, but is otherwise not especially useful. For async dispatch, an immediate dispatcher should generally be preferable.

Returns:

dispatcher

immediate

static Dispatcher immediate()

Returns a dispatcher that dispatches events to subscribers immediately as they're posted without using an intermediate queue to change the dispatch order. This is effectively a depth-first dispatch order, vs. breadth-first when using a queue.

Returns:

dispatcher

dispatch

abstract void dispatch(Object event,
                       Iterator<Subscriber> subscribers)

Dispatches the given event to the given subscribers.

Parameters:

event - event to dispatch

subscribers - subscribers to notify