org.fusesource.hawtdispatch

Interface Dispatcher

All Known Implementing Classes:

HawtDispatcher

public interface Dispatcher

The Dispatcher interface is used to get or create dispatch objects such as global queues, thread queues, serial queues, or dispatch sources.

The dispatch queues are Executor objects that execute tasks asynchronously on thread pools managed by the Dispatcher.

• Global Queues: The tasks submitted to a concurrent dispatch queue will execute concurrently on the first available thread of the thread pool. The order of execution of the tasks is non deterministic.
• Thread Queues: The tasks submitted to a thread dispatch queue will execute serially (FIFO order) on a single thread of the thread pool.
• Serial Queues: The tasks submitted to a serial dispatch queue will execute serially (FIFO order) on the first available thread of the thread pool.

All dispatch queues use a shared fixed size thread pool to execute tasks. All tasks submitted on a dispatch queue should be non-blocking and wait free.

Dispatch sources provide a way to trigger execution of a user task on on a user selected dispatch queue in response to NIO or application defined events.

Method Summary

Modifier and Type	Method and Description
DispatchQueue	createQueue(java.lang.String label) Creates a new serial dispatch queue to which runnable objects may be submitted.
<Event,MergedEvent> CustomDispatchSource<Event,MergedEvent>	createSource(EventAggregator<Event,MergedEvent> aggregator, DispatchQueue queue) Creates a new CustomDispatchSource to monitor events merged into the dispatch source and automatically submit a handler runnable to a dispatch queue in response to the events.
DispatchSource	createSource(java.nio.channels.SelectableChannel channel, int interestOps, DispatchQueue queue) Creates a new DispatchSource to monitor SelectableChannel objects and automatically submit a handler runnable to a dispatch queue in response to events.
DispatchQueue	getCurrentQueue() Returns the queue on which the currently executing runnable is running.
DispatchQueue	getCurrentThreadQueue()
DispatchQueue	getGlobalQueue() Returns the global concurrent queue of default priority.
DispatchQueue	getGlobalQueue(DispatchPriority priority) Returns a well-known global concurrent queue of a given priority level.
DispatchQueue[]	getThreadQueues(DispatchPriority priority)
java.util.List<Metrics>	metrics() Used to get profiling metrics for all the queues currently being profiled.
boolean	profile()
void	profile(boolean enabled) If enabled then it enables profiling on the global queues and any newly created queues.
void	restart() Restart this dispatcher instance.
void	shutdown() Shutdown this dispatcher instance.

Method Detail

getThreadQueues

DispatchQueue[] getThreadQueues(DispatchPriority priority)

Returns:

the thread level dispatch queues for a given dispatch priority.

getCurrentThreadQueue

DispatchQueue getCurrentThreadQueue()

Returns:

the current thread queue or null of not executing on a thread queue.

getGlobalQueue

DispatchQueue getGlobalQueue()

Returns the global concurrent queue of default priority.

Returns:

the default priority global queue.

See Also:

getGlobalQueue(DispatchPriority)

getGlobalQueue

DispatchQueue getGlobalQueue(DispatchPriority priority)

Returns a well-known global concurrent queue of a given priority level.

The well-known global concurrent queues may not be modified. Calls to Suspendable.suspend(), Suspendable.resume(), etc., will have no effect when used with queues returned by this function.

Parameters:

priority - A priority defined in dispatch_queue_priority_t

Returns:

the requested global queue.

createQueue

DispatchQueue createQueue(java.lang.String label)

Creates a new serial dispatch queue to which runnable objects may be submitted.

Serial dispatch queues execute runnables submitted to them serially in FIFO order. A queue will only invoke one runnable at a time, but independent queues may each execute their runnables concurrently with respect to each other.

Conceptually a dispatch queue may have its own thread of execution, and interaction between queues is highly asynchronous.

Parameters:

label - the label to assign the dispatch queue, can be null

Returns:

the newly created dispatch queue

getCurrentQueue

DispatchQueue getCurrentQueue()

Returns the queue on which the currently executing runnable is running.

When getCurrentQueue() is called outside of the context of a submitted runnable, it will return null.

Returns:

the queue on which the currently executing runnable is running.

createSource

DispatchSource createSource(java.nio.channels.SelectableChannel channel,
                            int interestOps,
                            DispatchQueue queue)

Creates a new DispatchSource to monitor SelectableChannel objects and automatically submit a handler runnable to a dispatch queue in response to events.

You are allowed to create multiple dispatch sources to the same SelectableChannel object.

Parameters:

channel - the channel to monitor.

interestOps - A mask of interest ops (SelectionKey.OP_ACCEPT, SelectionKey.OP_CONNECT, SelectionKey.OP_READ, or SelectionKey.OP_WRITE) specifying which events are desired.

queue - The dispatch queue to which the event handler tasks will be submited.

Returns:

the newly created DispatchSource

createSource

<Event,MergedEvent> CustomDispatchSource<Event,MergedEvent> createSource(EventAggregator<Event,MergedEvent> aggregator,
                                                                         DispatchQueue queue)

Creates a new CustomDispatchSource to monitor events merged into the dispatch source and automatically submit a handler runnable to a dispatch queue in response to the events.

Parameters:

aggregator - the data aggregation strategy to use.

queue - The dispatch queue to which the event handler tasks will be submited.

Returns:

the newly created CustomDispatchSource

profile

void profile(boolean enabled)

If enabled then it enables profiling on the global queues and any newly created queues. If not enabled then it disables profiling support on all the currently profiled queues and any queues created in the future.

Parameters:

enabled -

profile

boolean profile()

Returns:

true is profiling is enabled.

metrics

java.util.List<Metrics> metrics()

Used to get profiling metrics for all the queues currently being profiled.

Returns:

shutdown

void shutdown()

Shutdown this dispatcher instance.

restart

void restart()

Restart this dispatcher instance.