simple.util.process
Class ProcessQueue

java.lang.Object
  extended by java.util.Observable
      extended by simple.util.process.ProcessQueue

public final class ProcessQueue
extends java.util.Observable

The ProcessQueue object provides a means for quick independent executions. This is a thread cache, the aim of this is to make execution of Runnable objects quick. The Runnable objects given to this should be transient so that the thread can be reused. This should not be used as an easy way to access a thread.

When an object needs to be run in its own thread then usually a separate thread object needs to be created and initialized for that object to execute. However this is an expensive undertaking for the system. A cheaper way to execute the objects is to create a number of the threads and allow these threads to process Runnable objects when they are free, i.e. not busy with another Runnable. This removes the need for the expensive initialization of the threads for every execution of an object.

The ProcessQueue extends the Observable object. This enables any object that may be using this to receive notification when the ProcessQueue.resize is used. The need for notifications is evident when there is a small number of threads. If Runnable objects are executed, and remain in execution for a long time, the number of threads active can be equal to the number of threads pooled. This means that any object executing the execute method will be frozen waiting for a Runnable to finish.

Author:
Niall Gallagher

Method Summary
 int capacity()
          This will return the number of threads that this pool currently has cached.
 void execute(java.lang.Runnable target)
          This is used to execute the Runnable objects with one of the threads from the pool.
static ProcessQueue getInstance()
          This allows the ProcessQueue to become a system static object.
 void resize(int size)
          This is used to either increase or decrease the number of threads that are active in the ProcessQueue.
 void stop()
          This is a convenience method that is used to deactivate all the threads in the ProcessQueue this is similar a resize with zero.
 
Methods inherited from class java.util.Observable
addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getInstance

public static ProcessQueue getInstance()
This allows the ProcessQueue to become a system static object. This provides the system with a thread cache that can be shared by objects across the JVM. Caution should be taken when using the ProcessQueue, as it has a limited amount of threads. This means that if number of objects processing Runnable objects exceeded the number of threads then the objects would block waiting for the next thread to be available.

Because this is a singleton object, that is, an instance that is static for the entire JVM, access control must be required. The caller of this method must have the permission ProcessPermission with the "execute" action.

Returns:
returns the system static ProcessQueue
Throws:
java.lang.SecurityException - the caller needs permission

execute

public void execute(java.lang.Runnable target)
             throws java.lang.InterruptedException
This is used to execute the Runnable objects with one of the threads from the pool. This method is not synchronized so as many threads can invoke this method as needs be. If all threads are occupied then this will block waiting for the next available thread to be made ready.

Parameters:
target - the Runnable to be executed
Throws:
java.lang.InterruptedException - if there is an interrupt

resize

public void resize(int size)
This is used to either increase or decrease the number of threads that are active in the ProcessQueue. This is an internally synchronized method so if there are several threads using the ProcessQueue each will wait its turn before the resize is invoked. This is tricky when there a several threads trying to resize concurrently because the capacity may change.

This will notify all Observer of the change in the number of threads pooled. This passes all of the Observer objects the old capacity of the ProcessQueue as an Integer.

Parameters:
size - the number of threads that this is to use
Throws:
java.lang.InterruptedException - if there is an interrupt

capacity

public int capacity()
This will return the number of threads that this pool currently has cached. This can be used before the resize method to determine if there is a need for new threads to be activated or to be deactivated.

Returns:
the number of threads that this pool contains

stop

public void stop()
This is a convenience method that is used to deactivate all the threads in the ProcessQueue this is similar a resize with zero. This will continue to dequeue threads from the MessageQueue until all Daemon threads have ended.