/**
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2005 Sun Microsystems Inc. All Rights Reserved
*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the License). You may not use this file except in
* compliance with the License.
*
* You can obtain a copy of the License at
* See the License for the specific language governing
* permission and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* Header Notice in each file and include the License file
* at opensso/legal/CDDLv1.0.txt.
* If applicable, add the following below the CDDL Header,
* with the fields enclosed by brackets [] replaced by
* your own identifying information:
* "Portions Copyrighted [year] [name of copyright owner]"
*
* $Id: ThreadPool.java,v 1.3 2008/06/25 05:41:41 qcheng Exp $
*
*/
// TODO:
// Stopping individual tasks
// ThreadGroups
// Exception propagation or callbacks
/**
* <p>
* ThreadPool is a generic thread pool that manages and recycles threads instead
* of creating them everytime some task needs to be run on a different thread.
* Thread pooling saves the virtual machine the work of creating brand new
* threads for every short-lived task. In addition, it minimizes overhead
* associated with getting a thread started and cleaning it up after it dies. By
* creating a pool of threads, a single thread from the pool can be reused any
* number of times for different tasks.
* </p>
* <p>
* This reduces response time because a thread is already constructed and
* started and is simply waiting for its next task. This is particularly useful
* when using many short-lived tasks. This may not be useful for long-lived
* tasks.
* </p>
* <p>
* In future, this class may be enhanced to provide support growing the size of
* the pool at runtime to facilitate dynamic tuning.
* </p>
*/
public final class ThreadPool {
/**
* tail points to the last available idle thread in the idleThreadList. When
* the idleThreadList is empty, tail is set to -1. IMPORTANT: tail MUST
* always be accessed by acquiring a lock on idleThreadList. Otherwise, the
* code will break.
*/
/**
* <p>
* Constructs a thread pool with the poolName and given number of threads.
* </p>
*
* @param poolName
* name of the thread pool
* @param numThreads
* maximum number of threads in the thread pool.
* @param daemon
* if true, all threads created will be daemon threads. If false,
* all threads created will be non-daemon threads.
* @param debug
* Debug object to send debug messages to.
*
* @throws IllegalArgumentException
* if poolName is null
*/
} else {
throw new IllegalArgumentException(
"Must assign a non-null pool name to ThreadPool");
}
// ensure that there is at least one thread in the pool
// Normally Lists should be used. However, since this class is a
// performance-critical low level code, arrays are used to fully
// optmize.
// Now initialized only allThreads list. idleThreads list will be
// updated by the threads when they are idle and ready.
for (int i = 0; i < numThreads; ++i) {
}
}
/** Suppress the no-arg constructor because it is not supported */
private ThreadPool() {
}
/** Gets the unique name for the internal thread in the pool */
}
/**
* Runs the user-defined task. To enable better debugging or profiling
* capabilities, the <code>task</code> <code>Runnable</code> should
* implement <code>toString()</code> to intuitively identify the task.
*
* @param task
* the user-defined Runnable to be scheduled for execution on
* this thread pool
* @throws InterruptedException
* when the thread invoking <code>run</code> is interrupted.
*/
synchronized (idleThreadList) {
while (tail == -1) {
+ " waiting for an idle thread in " + toString());
}
}
// Now there is at least one idle thread available
// Now that the idle thread is off the idleThreadList, there is no
// danger of some other task being simultaneously assigned to that
// idle thread. Release the lock on idleThreadList now so that
// other tasks can be processed concurrently.
}
// logMessage(Thread.currentThread().getName() + " assigning task '" +
// task + "' to " + ipsThread.getName());
}
/**
* Stops all the idle threads in the pool. Note that these stopped threads
* are no longer availble for future tasks because they are returned to
* underlying virtual machine. Also note that none of the active threads in
* the pool are stopped.
*/
public final void stopIdleThreads() {
synchronized (idleThreadList) {
while (tail >= 0) {
idleThread.stop();
}
}
}
/**
* Destroys the thread pool. This stops all the threads, active and idle, in
* the pool and releases all resources.
*/
public final void destroy() {
// stop the idle threads first to be more productive
try {
// give the idle threads a chance to die
} catch (InterruptedException e) {
// no need to reassert InterruptedException here because the
// pool is being shutdown
}
// now go through allThreadList and stop everything
synchronized (allThreadList) {
int i = 0;
while (i < numThreads) {
allThreadList[i++] = null;
}
}
}
}
/**
* Returns the string representation of this thread pool that includes the
* name, size and the number of currently idle threads
*/
synchronized (idleThreadList) {
}
}
/** Returns the name of this thread pool */
return poolName;
}
return;
}
}
/** ******************************************************************** */
/** An inner class that actually executes the user-defined tasks. */
private final class IPSThread {
// This internal thread will handle only one task at a time
private volatile boolean stopped = false;
public void run() {
try {
runTask();
} catch (Throwable t) {
// In case any exception slips through
+ " caught exception that fell through", t);
}
}
}
};
}
/** Explicitly suppressed because it is not supported */
private IPSThread() {
}
/**
* Accepts the user-defined task for execution. Note that by design this
* method is called only when this thread is idle.
*/
throws InterruptedException {
// Since only one thread can wait on this object, notifyAll() is
// not used.
notify();
}
/**
* Actually runs the user-defined task. This thread adds itself to the
* idleThreadList in the parent pool and waits to be assinged a task.
* When the task is assinged, it goes ahead and executes it. While
* executing, this thread is not on the idleThreadList.
*/
private void runTask() {
while (!stopped) {
try {
// This thread is ready to rock-n-roll! Add this thread to
// the idleThreadList
synchronized (idleThreadList) {
idleThreadList[++tail] = this;
// If idleThreadList was empty, notify the waiting
// threads
if (tail == 0) {
}
}
// Now wait until the parent pool assigns this thread a task
synchronized (this) {
wait();
}
}
// logMessage(thread.getName() + " is running the task '" +
// task + "'");
try {
} catch (Exception e) {
" caught exception that fell through from "
+ task + ".run()", e);
}
} finally {
// Clear the interrupted flag (in case it comes back
// set) so that if the loops goes again, the task.wait()
// does not mistakenly throw an InterruptedException.
}
} catch (InterruptedException e) {
// This catch must be here (in addition to the one inside
// the corresponding try{}) so that a task is not run
// mistakenly after this thread is interrupted.
} catch (Throwable t) {
// Fatal exception occurred. But we don't want to stop this
// thread as that might only deplete the thread pool.
": runTask() caught throwable. Investigate " +
"the problem", t);
}
} finally {
// set task to null so that the task doesn't get executed
// repeatedly.
// logMessage(thread.getName() +
// " compeleted the task '" + task + "'");
}
}
}
}
/**
* Stops this thread. This method may return before this thread actually
* dies.
*/
private final void stop() {
stopped = true;
}
/** Gets the name of this thread */
}
/** Checks if this thread is alive or dead */
final boolean isAlive() {
}
}
}