ch.randelshofer.util
Class PooledSequentialDispatcher

java.lang.Object
  ch.randelshofer.util.PooledSequentialDispatcher

All Implemented Interfaces:

Dispatcher, java.lang.Runnable

public class PooledSequentialDispatcher
extends java.lang.Object
implements Dispatcher, java.lang.Runnable

Processes Runnable objects sequentially on a pool of processor threads. The order in which the runnable objects are processed is the same in which they were added to the dispatcher.

Per default, there is one pool per VM running 5 threads. You can assign the dispatcher to a different thread pool using the constructor or using method setThreadPool.

The static method dispatchConcurrently enqueues the runnable object for concurrent execution. That is, it will be processed as soon as one of the pooled threads becomes available.

The instance method dispatch enqueues the runnable object for sequential execution. It will be processed by one of the pooled threads when all of the preceedingly enqueued runnables have been processed. There is one queue per instance.

Design pattern used: Acceptor Role in design pattern: EventCollector and EventProcessor

Example 1
The following program prints "one", "two", "three" on concurrent processor threads:

 PooledSequentialDispatcher.dispatchConcurrently(
     new Runnable(public void run() { System.out.println("one"); });
 );
 PooledSequentialDispatcher.dispatchConcurrently(
     new Runnable(public void run() { System.out.println("two"); });
 );
 PooledSequentialDispatcher.dispatchConcurrently(
     new Runnable(public void run() { System.out.println("three"); });
 );
 

The order of the output is not granted, since the runnables are executed concurrently. It could be "one","two","three" or "three","one","two" or any other possible combination. Even intermingled output is possible.

Example 2
The following program prints "one", "two", "three" on sequential processor threads:

 PooledSequentialDispatcher dispatcher = new PooledSequentialDispatcher();

 dispatcher.dispatch(
     new Runnable(public void run() { System.out.println("one"); });
 );
 dispatcher.dispatch(
     new Runnable(public void run() { System.out.println("two"); });
 );
 dispatcher.dispatch(
     new Runnable(public void run() { System.out.println("three"); });
 );
 

Since all runnables are dispatched by the same PoolDispatcherAWT instance, it is granted, that they will be executed in the same order as they were added to the queue. It is also granted, that the output will not be intermingled, because a runnable will be executed only, when its predecessor has finished.

Version:

1.1.1 2007-12-25 Fixed null pointer in static dispatch method.
1.1 2003-04-05 Method stop() invokes wait() now on object 'queue' and not on thisi object.
1.0.1 2001-12-31 Comments translated into english.
1.0 2001-12-27 Created.

Author:

Werner Randelshofer, Hausmatt 10, Immensee, CH-6405, Switzerland

Constructor Summary

PooledSequentialDispatcher()
Creates a new PooledSequentialDispatcher which uses the global threadPool for dispatching its queue.

Method Summary

void	dispatch(java.lang.Runnable runner) Enqueues the Runnable object, and executes it sequentially on one of the processor threads of the thread pool associated with this class.
void	dispatch(java.lang.Runnable runner, ConcurrentDispatcher pool) Enqueues the Runnable object, and executes it sequentially on one of the processor threads of the specified thread pool or - if there is already a thread associated with the queue - on that thread.
static void	dispatchConcurrently(java.lang.Runnable runner) Enqueues the Runnable object, and executes it concurrently by one of the processor threads.
int	getMaxThreadCount() Retunrs the maximal number of concurrent threads.
ConcurrentDispatcher	getThreadPool() Returns the underlying thread pool.
void	join()
void	reassign() (Re)starts the Reassigns the queue to the thread pool provided by this class.
void	run() This method is public as a side effect of the implementation of this class.
void	setMaxThreadCount(int maxThreadCount) Sets the maximum number of concurrent threads.
void	setThreadPool(ConcurrentDispatcher threadPool) Assigns this dispatcher to the specified thread pool.
void	start() Starts the event processor.
void	stop() Stops the event processor and waits until it has finished.

Methods inherited from class java.lang.Object

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

Constructor Detail

PooledSequentialDispatcher

public PooledSequentialDispatcher()

Creates a new PooledSequentialDispatcher which uses the global threadPool for dispatching its queue.

Method Detail

setMaxThreadCount

public void setMaxThreadCount(int maxThreadCount)

Sets the maximum number of concurrent threads.

Parameters:

maxThreadCount - Maximal number of concurrent threads. A value of zero or below zero stops the dispatcher when the queue is empty.

getMaxThreadCount

public int getMaxThreadCount()

Retunrs the maximal number of concurrent threads.

setThreadPool

public void setThreadPool(ConcurrentDispatcher threadPool)

Assigns this dispatcher to the specified thread pool.

getThreadPool

public ConcurrentDispatcher getThreadPool()

Returns the underlying thread pool.

dispatchConcurrently

public static void dispatchConcurrently(java.lang.Runnable runner)

Enqueues the Runnable object, and executes it concurrently by one of the processor threads. The runnables are not necesseraly executed in the same order as they were enqueued.

Parameters:

runner - A runnable.

dispatch

public void dispatch(java.lang.Runnable runner)

Enqueues the Runnable object, and executes it sequentially on one of the processor threads of the thread pool associated with this class. The runnables are executed in the same order as they were enqueued.

Specified by:

dispatch in interface Dispatcher

Parameters:

runner - A runnable.

dispatch

public void dispatch(java.lang.Runnable runner,
                     ConcurrentDispatcher pool)

Enqueues the Runnable object, and executes it sequentially on one of the processor threads of the specified thread pool or - if there is already a thread associated with the queue - on that thread. The runnables are executed in the same order as they were enqueued.

Parameters:

runner - A runnable.

See Also:

reassign()

reassign

public void reassign()

(Re)starts the Reassigns the queue to the thread pool provided by this class.

start

public void start()

Starts the event processor.

stop

public void stop()

Stops the event processor and waits until it has finished.

run

public void run()

This method is public as a side effect of the implementation of this class. Do not call this method from outside this class.

This method dequeues all Runnable objects from the queue and executes them. The method returns when the queue is empty.

Specified by:

run in interface java.lang.Runnable

join

public void join()
          throws java.lang.InterruptedException

Specified by:

join in interface Dispatcher

Throws:

java.lang.InterruptedException