org.fusesource.hawtdispatch

Class Dispatch

java.lang.Object

org.fusesource.hawtdispatch.Dispatch

public class Dispatch
extends java.lang.Object

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

It is encouraged that end users of this api do a static import of the methods defined in this class.

 import static org.fusesource.hawtdispatch.Dispatch.*;
 

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.

Field Summary

Fields

Modifier and Type	Field and Description
static DispatchPriority	DEFAULT
private static Dispatcher	DISPATCHER
static DispatchPriority	HIGH
static DispatchPriority	LOW
static Task	NOOP A Runnable task that does nothing.

Constructor Summary

Constructors

Constructor and Description
Dispatch()

Method Summary

Modifier and Type	Method and Description
static DispatchQueue	createQueue() Creates a new serial dispatch queue to which runnable objects may be submitted.
static DispatchQueue	createQueue(java.lang.String label) Creates a new serial dispatch queue to which runnable objects may be submitted.
static <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.
static 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.
static DispatchQueue	getCurrentQueue() Returns the queue on which the currently executing runnable is running.
static DispatchQueue	getCurrentThreadQueue()
static DispatchQueue	getGlobalQueue() Returns the global concurrent queue of default priority.
static DispatchQueue	getGlobalQueue(DispatchPriority priority) Returns a well-known global concurrent queue of a given priority level.
static DispatchQueue[]	getThreadQueues(DispatchPriority priority)
static java.util.List<Metrics>	metrics() Used to get profiling metrics for all the queues currently being profiled.
static void	profile(boolean enabled) If enabled then it enables profiling on the global queues and any newly created queues.
static void	restart() Restart default dispatcher instance.
static void	shutdown() Shutdown default dispatcher instance.

Methods inherited from class java.lang.Object

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

Field Detail

DISPATCHER

private static final Dispatcher DISPATCHER

HIGH

public static final DispatchPriority HIGH

DEFAULT

public static final DispatchPriority DEFAULT

LOW

public static final DispatchPriority LOW

NOOP

public static final Task NOOP

A Runnable task that does nothing.

Constructor Detail

Dispatch

public Dispatch()

Method Detail

getGlobalQueue

public static DispatchQueue getGlobalQueue()

Returns the global concurrent queue of default priority.

Returns:

the default priority global queue.

See Also:

getGlobalQueue(DispatchPriority)

getGlobalQueue

public static 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

public static 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

createQueue

public static DispatchQueue createQueue()

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

Same thing as createQueue(null)

Returns:

the newly created dispatch queue

See Also:

createQueue(String)

getCurrentQueue

public static 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

public static 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

public static <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

getThreadQueues

public static DispatchQueue[] getThreadQueues(DispatchPriority priority)

Returns:

the thread level dispatch queues for a given dispatch priority.

getCurrentThreadQueue

public static DispatchQueue getCurrentThreadQueue()

Returns:

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

profile

public static 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 -

metrics

public static java.util.List<Metrics> metrics()

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

Returns:

shutdown

public static void shutdown()

Shutdown default dispatcher instance.

restart

public static void restart()

Restart default dispatcher instance.