util/concurrent/ThreadPoolExecutor.java

/*
 * @(#)ThreadPoolExecutor.java
 */

package java.util.concurrent;

import java.util.List;

/**
 * A {@link ThreadedExecutor} that executes each submitted task on one
 * of several pooled threads.
 *
 * <p>Thread pools address two different problems at the same time:
 * they usually provide improved performance when executing large
 * numbers of asynchronous tasks, due to reduced per-task invocation
 * overhead, and they provide a means of bounding and managing the
 * resources, including threads, consumed in executing a collection of
 * tasks.
 *
 * <p>This class is very configurable and can be configured to create
 * a new thread for each task, or even to execute tasks sequentially
 * in a single thread, in addition to its most common configuration,
 * which reuses a pool of threads.
 *
 * <p>To be useful across a wide range of contexts, this class
 * provides many adjustable parameters and extensibility hooks.
 * However, programmers are urged to use the more convenient factory
 * methods <tt>newCachedThreadPool</tt> (unbounded thread pool, with
 * automatic thread reclamation), <tt>newFixedThreadPool</tt> (fixed
 * size thread pool), <tt>newSingleThreadExecutor</tt> (single
 * background thread for execution of tasks), and
 * <tt>newThreadPerTaskExeceutor</tt> (execute each task in a new
 * thread), that preconfigure settings for the most common usage
 * scenarios.
 *
 *
 * <p>This class also maintain some basic statistics, such as the
 * maximum number of active threads, or the maximum queue length, that
 * may be useful for monitoring and tuning executors.
 *
 * <h3>Tuning guide</h3>
 * <dl>
 * <dt>Minimum and maximum pool size</dt>
 * <dd>ThreadExecutor will
 * automatically adjust the pool size within the bounds set by
 * minimumPoolSize and maximumPoolSize.  When a new task is submitted,
 * and fewer than the minimum number of threads are running, a new
 * thread is created to handle the request, even if other worker
 * threads are idle.  If there are more than the minimum but less than
 * the maximum number of threads running, a new thread will be created
 * only if all other threads are busy.  By setting minimumPoolSize and
 * maximumPoolSize to N, you create a fixed-size thread pool.</dd>
 *
 * <dt>Keep-alive</dt>
 * <dd>The keepAliveTime determines what happens to idle
 * threads.  If the pool currently has more than the minimum number of
 * threads, excess threads will be terminated if they have been idle
 * for more than the keepAliveTime.</dd>
 *
 * <dt>Queueing</dt>
 * <dd>You are free to specify the queuing mechanism used
 * to handle submitted tasks.  The newCachedThreadPool factory method
 * uses queueless synchronous channels to to hand off work to threads.
 * This is a safe, conservative policy that avoids lockups when
 * handling sets of requests that might have internal dependencies.
 * The newFixedThreadPool factory method uses a LinkedBlockingQueue,
 * which will cause new tasks to be queued in cases where all
 * MaximumPoolSize threads are busy.  Queues are sometimes appropriate
 * when each task is completely independent of others, so tasks cannot
 * affect each others execution. For example, in an http server.  When
 * given a choice, this pool always prefers adding a new thread rather
 * than queueing if there are currently fewer than the current
 * getMinimumPoolSize threads running, but otherwise always prefers
 * queuing a request rather than adding a new thread.
 *
 * <p>While queuing can be useful in smoothing out transient bursts of
 * requests, especially in socket-based services, it is not very well
 * behaved when commands continue to arrive on average faster than
 * they can be processed.  Using a bounded queue implements an overflow
 * policy which drops requests which cannot be handled due to insufficient
 * capacity.
 *
 * Queue sizes and maximum pool sizes can often be traded off for each
 * other. Using large queues and small pools minimizes CPU usage, OS
 * resources, and context-switching overhead, but can lead to
 * artifically low throughput.  If tasks frequently block (for example
 * if they are I/O bound), a JVM and underlying OS may be able to
 * schedule time for more threads than you otherwise allow. Use of
 * small queues or queueless handoffs generally requires larger pool
 * sizes, which keeps CPUs busier but may encounter unacceptable
 * scheduling overhead, which also decreases throughput.
 * </dd>
 * <dt>Creating new threads</dt>
 * <dd>New threads are created through the
 * Callbacks.  By default, threads are created simply with
 * the new Thread(Runnable) constructor, but by overriding
 * Callbacks.newThread, you can alter the thread's name,
 * thread group, priority, daemon status, etc.
 * </dd>
 * <dt>Before and after intercepts</dt>
 * <dd>The Callbacks class has
 * methods which are called before and after execution of a task.
 * These can be used to manipulate the execution environment (for
 * example, reinitializing ThreadLocals), gather statistics, or
 * perform logging.
 * </dd>
 * <dt>Blocked execution</dt>
 * <dd>There are a number of factors which can
 * bound the number of tasks which can execute at once, including the
 * maximum pool size and the queuing mechanism used.  If you are using
 * a synchronous queue, the execute() method will block until threads
 * are available to execute.  If you are using a bounded queue, then
 * tasks will be discarded if the bound is reached.  If the executor
 * determines that a task cannot be executed because it has been
 * refused by the queue and no threads are available, the
 * Callbacks.cannotExecute method will be called.
 * </dd>
 * <dt>Termination</dt>
 * <dd>ThreadExecutor supports two shutdown options,
 * immediate and graceful.  In an immediate shutdown, any threads
 * currently executing are interrupted, and any tasks not yet begun
 * are returned from the shutdownNow call.  In a graceful shutdown,
 * all queued tasks are allowed to run, but new tasks may not be
 * submitted.
 * </dd>
 * </dl>
 *
 * @since 1.5
 * @see CannotExecuteHandler
 * @see Executors
 * @see ThreadFactory
 *
 * @spec JSR-166
 * @revised $Date: 2003/03/12 18:32:40 $
 * @editor $Author: tim $
 *
 * @fixme If greater control is needed, you can use the
 *        constructor with custom parameters, selectively override
 *        <tt>Callbacks</tt>, and/or dynamically change tuning
 *        parameters
 *
 * @fixme <br/> Brian copied some stuff from dl.u.c for the tuning guide; please
 *        review to make sure that it is still correct
 *
 * @fixme <br/> Please check if Brian's statements about queuing and blocking
 *        in the tuning guide are correct.
 */
public class ThreadPoolExecutor implements ThreadedExecutor {

    /**
     * Creates a new <tt>ThreadPoolExecutor</tt> with the given initial
     * parameters.  It may be more convenient to use one of the factory
     * methods instead of this general purpose constructor.
     *
     * @param minThreads the minimum number of threads to keep in the
     * pool, even if they are idle.
     * @param maxThreads the maximum number of threads to allow in the
     * pool.
     * @param keepAliveTime when the number of threads is greater than
     * the minimum, this is the maximum time that excess idle threads
     * will wait for new tasks before terminating.
     * @param granularity the time unit for the keepAliveTime
     * argument.
     * @param workQueue the queue to use for holding tasks before the
     * are executed. This queue will hold only the <tt>Runnable</tt>
     * tasks submitted by the <tt>execute</tt> method.
     * @throws IllegalArgumentException if minThreads, maxThreads, or
     * keepAliveTime less than zero, or if minThreads greater than
     * maxThreads.
     * @throws NullPointerException if <tt>workQueue</tt> is null
     */
    public ThreadPoolExecutor(int minThreads,
                              int maxThreads,
                              long keepAliveTime,
                              TimeUnit granularity,
                              BlockingQueue workQueue) {}

    /* Executor implementation. Inherit javadoc from ThreadedExecutor. */

    public void execute(Runnable command) {}

    /* ThreadedExecutor implementation.  Inherit javadoc. */

    public void setThreadFactory(ThreadFactory threadFactory) {
    }

    public ThreadFactory getThreadFactory() {
        return null;
    }

    public void setCannotExecuteHandler(CannotExecuteHandler handler) {
    }

    public CannotExecuteHandler getCannotExecuteHandler() {
        return null;
    }

    public BlockingQueue getQueue() {
        return null;
    }

    public void shutdown() {}

    public List shutdownNow() {
        return null;
    }

    public boolean isShutdown() {
        return false;
    }

    public void interrupt() {}

    public boolean isTerminated() {
        return false;
    }

    public boolean awaitTermination(long timeout, TimeUnit granularity)
            throws InterruptedException {
        return false;
    }

    /* @fixme Should any of these be included in ThreadedExecutor interface? */

    /**
     * Sets the minimum allowed number of threads.  This overrides any
     * value set in the constructor.
     *
     * @param minThreads the new minimum
     * @throws IllegalArgumentException if <tt>minThreads</tt> less than zero
     */
    public void setMinimumPoolSize(int minThreads) {}

    /**
     * Returns the minimum allowed number of threads.
     *
     * @return the minimum number of threads
     */
    public int getMinimumPoolSize() { return 0; }

    /**
     * Sets the maximum allowed number of threads. This overrides any
     * value set in the constructor.
     *
     * @param maxThreads the new maximum
     * @throws IllegalArgumentException if maxThreads less than zero or
     * the {@link #getMinimumPoolSize minimum pool size}
     */
    public void setMaximumPoolSize(int maxThreads) {}

    /**
     * Returns the maximum allowed number of threads.
     *
     * @return the maximum number of threads
     */
    public int getMaximumPoolSize() { return 0; }

    /**
     * Sets the time limit for which threads may remain idle before
     * being terminated.  If there are more than the minimum number of
     * threads currently in the pool, after waiting this amount of
     * time without processing a task, excess threads will be
     * terminated.  This overrides any value set in the constructor.
     * @param time the time to wait.  A time value of zero will cause
     * excess threads to terminate immediately after executing tasks.
     * @param granularity  the time unit of the time argument
     * @throws IllegalArgumentException if msecs less than zero
     */
    public void setKeepAliveTime(long time, TimeUnit granularity) {}

    /**
     * Returns the thread keep-alive time, which is the amount of time
     * which threads in excess of the minimum pool size may remain
     * idle before being terminated.
     *
     * @param granularity the desired time unit of the result
     * @return the time limit
     */
    public long getKeepAliveTime(TimeUnit granularity) { return 0; }

    /* Statistics */

    /**
     * Returns the current number of threads in the pool.
     *
     * @return the number of threads
     */
    public int getPoolSize() { return 0; }

    /**
     * Returns the current number of threads that are actively
     * executing tasks.
     *
     * @return the number of threads
     */
    public int getActiveCount() { return 0; }

    /**
     * Returns the maximum number of threads that have ever simultaneously
     * executed tasks.
     *
     * @return the number of threads
     */
    public int getMaximumActiveCount() { return 0; }

    /**
     * Returns the number of tasks that have been queued but not yet executed.
     *
     * @return the number of tasks
     */
    public int getQueueCount() { return 0; }

    /**
     * Returns the maximum number of tasks that have ever been queued
     * waiting for execution.
     *
     * @return the number of tasks
     */
    public int getMaximumQueueCount() { return 0; }

    /**
     * Returns the total number of tasks that have been scheduled for execution.
     *
     * @return the number of tasks
     */
    public int getCumulativeTaskCount() { return 0; }

    /**
     * Returns the total number of tasks that have completed execution.
     *
     * @return the number of tasks
     */
    public int getCumulativeCompletedTaskCount() { return 0; }

    /* @fixme Various CannotExecuteHandler implementations. */

    /**
     * A handler for unexecutable tasks that runs these tasks directly in the
     * calling thread of the <tt>execute</tt> method.  This is the default
     * <tt>CannotExecuteHandler</tt>.
     */
   public class CallerRunsPolicy implements CannotExecuteHandler {

        /**
         * Constructs a <tt>CallerRunsPolicy</tt>.
         */
        public CallerRunsPolicy() { }

        public boolean cannotExecute(Runnable r, boolean isShutdown) {
            if (!isShutdown) {
                r.run();
            }
            return true;
        }
    }

    /**
     * A handler for unexecutable tasks that throws a <tt>CannotExecuteException</tt>.
     */
    public class AbortPolicy implements CannotExecuteHandler {

        /**
         * Constructs a <tt>AbortPolicy</tt>.
         */
        public AbortPolicy() { }

        public boolean cannotExecute(Runnable r, boolean isShutdown) {
            if (!isShutdown) {
                throw new CannotExecuteException();
            }
            return true;
        }
    }

    /**
     * A handler for unexecutable tasks that waits until the task can be
     * submitted for execution.
     */
    public class WaitPolicy implements CannotExecuteHandler {

        /**
         * Constructs a <tt>WaitPolicy</tt>.
         */
        public WaitPolicy() { }

        public boolean cannotExecute(Runnable r, boolean isShutdown) {
            if (!isShutdown) {
                // FIXME: wait here
                // FIXME: throw CannotExecuteException if interrupted
                return false;
            }
            return true;
        }
    }

    /**
     * A handler for unexecutable tasks that silently discards these tasks.
     */
    public class DiscardPolicy implements CannotExecuteHandler {

        /**
         * Constructs <tt>DiscardPolicy</tt>.
         */
        public DiscardPolicy() { }

        public boolean cannotExecute(Runnable r, boolean isShutdown) {
            return true;
        }
    }

    /**
     * A handler for unexecutable tasks that discards the oldest unhandled request.
     */
    public class DiscardOldestPolicy implements CannotExecuteHandler {

        /**
         * Constructs a <tt>DiscardOldestPolicy</tt>.
         */
        public DiscardOldestPolicy() { }

        public boolean cannotExecute(Runnable r, boolean isShutdown) {
            if (!isShutdown) {
                // FIXME: discard oldest here
                return false;
            }
            return true;
        }
    }

    /*
     * Methods invoked during various points of execution, allowing fine-grained
     * control and monitoring.
     */

    /**
     * Method invoked prior to executing the given Runnable in given
     * thread.  This method may be used to re-initialize ThreadLocals,
     * or to perform logging.
     *
     * @param t the thread that will run task r.
     * @param r the task that will be executed.
     */
    protected void beforeExecute(Thread t, Runnable r) { }

    /**
     * Method invoked upon completion of execution of the given
     * Runnable.  If non-null, the Throwable is the uncaught exception
     * that caused execution to terminate abruptly.
     *
     * @param r the runnable that has completed.
     * @param t the exception that cause termination, or null if
     * execution completed normally.
     */
    protected void afterExecute(Runnable r, Throwable t) { }

    /**
     * Method invoked when the Executor has terminated.  Default
     * implementation does nothing.
     */
    protected void terminated() { }
}
Revision:	1.1
Committed:	Wed May 14 21:30:48 2003 UTC (21 years, 1 month ago) by tim
Branch:	MAIN
Log Message:	Moved main source rooted at . to ./src/main Moved test source rooted at ./etc/testcases to ./src/test
#	Content
1	/*
2	* @(#)ThreadPoolExecutor.java
3	*/
4
5	package java.util.concurrent;
6
7	import java.util.List;
8
9	/**
10	* A {@link ThreadedExecutor} that executes each submitted task on one
11	* of several pooled threads.
12	*
13	* <p>Thread pools address two different problems at the same time:
14	* they usually provide improved performance when executing large
15	* numbers of asynchronous tasks, due to reduced per-task invocation
16	* overhead, and they provide a means of bounding and managing the
17	* resources, including threads, consumed in executing a collection of
18	* tasks.
19	*
20	* <p>This class is very configurable and can be configured to create
21	* a new thread for each task, or even to execute tasks sequentially
22	* in a single thread, in addition to its most common configuration,
23	* which reuses a pool of threads.
24	*
25	* <p>To be useful across a wide range of contexts, this class
26	* provides many adjustable parameters and extensibility hooks.
27	* However, programmers are urged to use the more convenient factory
28	* methods <tt>newCachedThreadPool</tt> (unbounded thread pool, with
29	* automatic thread reclamation), <tt>newFixedThreadPool</tt> (fixed
30	* size thread pool), <tt>newSingleThreadExecutor</tt> (single
31	* background thread for execution of tasks), and
32	* <tt>newThreadPerTaskExeceutor</tt> (execute each task in a new
33	* thread), that preconfigure settings for the most common usage
34	* scenarios.
35	*
36	*
37	* <p>This class also maintain some basic statistics, such as the
38	* maximum number of active threads, or the maximum queue length, that
39	* may be useful for monitoring and tuning executors.
40	*
41	* <h3>Tuning guide</h3>
42	* <dl>
43	* <dt>Minimum and maximum pool size</dt>
44	* <dd>ThreadExecutor will
45	* automatically adjust the pool size within the bounds set by
46	* minimumPoolSize and maximumPoolSize. When a new task is submitted,
47	* and fewer than the minimum number of threads are running, a new
48	* thread is created to handle the request, even if other worker
49	* threads are idle. If there are more than the minimum but less than
50	* the maximum number of threads running, a new thread will be created
51	* only if all other threads are busy. By setting minimumPoolSize and
52	* maximumPoolSize to N, you create a fixed-size thread pool.</dd>
53	*
54	* <dt>Keep-alive</dt>
55	* <dd>The keepAliveTime determines what happens to idle
56	* threads. If the pool currently has more than the minimum number of
57	* threads, excess threads will be terminated if they have been idle
58	* for more than the keepAliveTime.</dd>
59	*
60	* <dt>Queueing</dt>
61	* <dd>You are free to specify the queuing mechanism used
62	* to handle submitted tasks. The newCachedThreadPool factory method
63	* uses queueless synchronous channels to to hand off work to threads.
64	* This is a safe, conservative policy that avoids lockups when
65	* handling sets of requests that might have internal dependencies.
66	* The newFixedThreadPool factory method uses a LinkedBlockingQueue,
67	* which will cause new tasks to be queued in cases where all
68	* MaximumPoolSize threads are busy. Queues are sometimes appropriate
69	* when each task is completely independent of others, so tasks cannot
70	* affect each others execution. For example, in an http server. When
71	* given a choice, this pool always prefers adding a new thread rather
72	* than queueing if there are currently fewer than the current
73	* getMinimumPoolSize threads running, but otherwise always prefers
74	* queuing a request rather than adding a new thread.
75	*
76	* <p>While queuing can be useful in smoothing out transient bursts of
77	* requests, especially in socket-based services, it is not very well
78	* behaved when commands continue to arrive on average faster than
79	* they can be processed. Using a bounded queue implements an overflow
80	* policy which drops requests which cannot be handled due to insufficient
81	* capacity.
82	*
83	* Queue sizes and maximum pool sizes can often be traded off for each
84	* other. Using large queues and small pools minimizes CPU usage, OS
85	* resources, and context-switching overhead, but can lead to
86	* artifically low throughput. If tasks frequently block (for example
87	* if they are I/O bound), a JVM and underlying OS may be able to
88	* schedule time for more threads than you otherwise allow. Use of
89	* small queues or queueless handoffs generally requires larger pool
90	* sizes, which keeps CPUs busier but may encounter unacceptable
91	* scheduling overhead, which also decreases throughput.
92	* </dd>
93	* <dt>Creating new threads</dt>
94	* <dd>New threads are created through the
95	* Callbacks. By default, threads are created simply with
96	* the new Thread(Runnable) constructor, but by overriding
97	* Callbacks.newThread, you can alter the thread's name,
98	* thread group, priority, daemon status, etc.
99	* </dd>
100	* <dt>Before and after intercepts</dt>
101	* <dd>The Callbacks class has
102	* methods which are called before and after execution of a task.
103	* These can be used to manipulate the execution environment (for
104	* example, reinitializing ThreadLocals), gather statistics, or
105	* perform logging.
106	* </dd>
107	* <dt>Blocked execution</dt>
108	* <dd>There are a number of factors which can
109	* bound the number of tasks which can execute at once, including the
110	* maximum pool size and the queuing mechanism used. If you are using
111	* a synchronous queue, the execute() method will block until threads
112	* are available to execute. If you are using a bounded queue, then
113	* tasks will be discarded if the bound is reached. If the executor
114	* determines that a task cannot be executed because it has been
115	* refused by the queue and no threads are available, the
116	* Callbacks.cannotExecute method will be called.
117	* </dd>
118	* <dt>Termination</dt>
119	* <dd>ThreadExecutor supports two shutdown options,
120	* immediate and graceful. In an immediate shutdown, any threads
121	* currently executing are interrupted, and any tasks not yet begun
122	* are returned from the shutdownNow call. In a graceful shutdown,
123	* all queued tasks are allowed to run, but new tasks may not be
124	* submitted.
125	* </dd>
126	* </dl>
127	*
128	* @since 1.5
129	* @see CannotExecuteHandler
130	* @see Executors
131	* @see ThreadFactory
132	*
133	* @spec JSR-166
134	* @revised $Date: 2003/03/12 18:32:40 $
135	* @editor $Author: tim $
136	*
137	* @fixme If greater control is needed, you can use the
138	* constructor with custom parameters, selectively override
139	* <tt>Callbacks</tt>, and/or dynamically change tuning
140	* parameters
141	*
142	* @fixme <br/> Brian copied some stuff from dl.u.c for the tuning guide; please
143	* review to make sure that it is still correct
144	*
145	* @fixme <br/> Please check if Brian's statements about queuing and blocking
146	* in the tuning guide are correct.
147	*/
148	public class ThreadPoolExecutor implements ThreadedExecutor {
149
150	/**
151	* Creates a new <tt>ThreadPoolExecutor</tt> with the given initial
152	* parameters. It may be more convenient to use one of the factory
153	* methods instead of this general purpose constructor.
154	*
155	* @param minThreads the minimum number of threads to keep in the
156	* pool, even if they are idle.
157	* @param maxThreads the maximum number of threads to allow in the
158	* pool.
159	* @param keepAliveTime when the number of threads is greater than
160	* the minimum, this is the maximum time that excess idle threads
161	* will wait for new tasks before terminating.
162	* @param granularity the time unit for the keepAliveTime
163	* argument.
164	* @param workQueue the queue to use for holding tasks before the
165	* are executed. This queue will hold only the <tt>Runnable</tt>
166	* tasks submitted by the <tt>execute</tt> method.
167	* @throws IllegalArgumentException if minThreads, maxThreads, or
168	* keepAliveTime less than zero, or if minThreads greater than
169	* maxThreads.
170	* @throws NullPointerException if <tt>workQueue</tt> is null
171	*/
172	public ThreadPoolExecutor(int minThreads,
173	int maxThreads,
174	long keepAliveTime,
175	TimeUnit granularity,
176	BlockingQueue workQueue) {}
177
178	/* Executor implementation. Inherit javadoc from ThreadedExecutor. */
179
180	public void execute(Runnable command) {}
181
182	/* ThreadedExecutor implementation. Inherit javadoc. */
183
184	public void setThreadFactory(ThreadFactory threadFactory) {
185	}
186
187	public ThreadFactory getThreadFactory() {
188	return null;
189	}
190
191	public void setCannotExecuteHandler(CannotExecuteHandler handler) {
192	}
193
194	public CannotExecuteHandler getCannotExecuteHandler() {
195	return null;
196	}
197
198	public BlockingQueue getQueue() {
199	return null;
200	}
201
202	public void shutdown() {}
203
204	public List shutdownNow() {
205	return null;
206	}
207
208	public boolean isShutdown() {
209	return false;
210	}
211
212	public void interrupt() {}
213
214	public boolean isTerminated() {
215	return false;
216	}
217
218	public boolean awaitTermination(long timeout, TimeUnit granularity)
219	throws InterruptedException {
220	return false;
221	}
222
223	/* @fixme Should any of these be included in ThreadedExecutor interface? */
224
225	/**
226	* Sets the minimum allowed number of threads. This overrides any
227	* value set in the constructor.
228	*
229	* @param minThreads the new minimum
230	* @throws IllegalArgumentException if <tt>minThreads</tt> less than zero
231	*/
232	public void setMinimumPoolSize(int minThreads) {}
233
234	/**
235	* Returns the minimum allowed number of threads.
236	*
237	* @return the minimum number of threads
238	*/
239	public int getMinimumPoolSize() { return 0; }
240
241	/**
242	* Sets the maximum allowed number of threads. This overrides any
243	* value set in the constructor.
244	*
245	* @param maxThreads the new maximum
246	* @throws IllegalArgumentException if maxThreads less than zero or
247	* the {@link #getMinimumPoolSize minimum pool size}
248	*/
249	public void setMaximumPoolSize(int maxThreads) {}
250
251	/**
252	* Returns the maximum allowed number of threads.
253	*
254	* @return the maximum number of threads
255	*/
256	public int getMaximumPoolSize() { return 0; }
257
258	/**
259	* Sets the time limit for which threads may remain idle before
260	* being terminated. If there are more than the minimum number of
261	* threads currently in the pool, after waiting this amount of
262	* time without processing a task, excess threads will be
263	* terminated. This overrides any value set in the constructor.
264	* @param time the time to wait. A time value of zero will cause
265	* excess threads to terminate immediately after executing tasks.
266	* @param granularity the time unit of the time argument
267	* @throws IllegalArgumentException if msecs less than zero
268	*/
269	public void setKeepAliveTime(long time, TimeUnit granularity) {}
270
271	/**
272	* Returns the thread keep-alive time, which is the amount of time
273	* which threads in excess of the minimum pool size may remain
274	* idle before being terminated.
275	*
276	* @param granularity the desired time unit of the result
277	* @return the time limit
278	*/
279	public long getKeepAliveTime(TimeUnit granularity) { return 0; }
280
281	/* Statistics */
282
283	/**
284	* Returns the current number of threads in the pool.
285	*
286	* @return the number of threads
287	*/
288	public int getPoolSize() { return 0; }
289
290	/**
291	* Returns the current number of threads that are actively
292	* executing tasks.
293	*
294	* @return the number of threads
295	*/
296	public int getActiveCount() { return 0; }
297
298	/**
299	* Returns the maximum number of threads that have ever simultaneously
300	* executed tasks.
301	*
302	* @return the number of threads
303	*/
304	public int getMaximumActiveCount() { return 0; }
305
306	/**
307	* Returns the number of tasks that have been queued but not yet executed.
308	*
309	* @return the number of tasks
310	*/
311	public int getQueueCount() { return 0; }
312
313	/**
314	* Returns the maximum number of tasks that have ever been queued
315	* waiting for execution.
316	*
317	* @return the number of tasks
318	*/
319	public int getMaximumQueueCount() { return 0; }
320
321	/**
322	* Returns the total number of tasks that have been scheduled for execution.
323	*
324	* @return the number of tasks
325	*/
326	public int getCumulativeTaskCount() { return 0; }
327
328	/**
329	* Returns the total number of tasks that have completed execution.
330	*
331	* @return the number of tasks
332	*/
333	public int getCumulativeCompletedTaskCount() { return 0; }
334
335	/* @fixme Various CannotExecuteHandler implementations. */
336
337	/**
338	* A handler for unexecutable tasks that runs these tasks directly in the
339	* calling thread of the <tt>execute</tt> method. This is the default
340	* <tt>CannotExecuteHandler</tt>.
341	*/
342	public class CallerRunsPolicy implements CannotExecuteHandler {
343
344	/**
345	* Constructs a <tt>CallerRunsPolicy</tt>.
346	*/
347	public CallerRunsPolicy() { }
348
349	public boolean cannotExecute(Runnable r, boolean isShutdown) {
350	if (!isShutdown) {
351	r.run();
352	}
353	return true;
354	}
355	}
356
357	/**
358	* A handler for unexecutable tasks that throws a <tt>CannotExecuteException</tt>.
359	*/
360	public class AbortPolicy implements CannotExecuteHandler {
361
362	/**
363	* Constructs a <tt>AbortPolicy</tt>.
364	*/
365	public AbortPolicy() { }
366
367	public boolean cannotExecute(Runnable r, boolean isShutdown) {
368	if (!isShutdown) {
369	throw new CannotExecuteException();
370	}
371	return true;
372	}
373	}
374
375	/**
376	* A handler for unexecutable tasks that waits until the task can be
377	* submitted for execution.
378	*/
379	public class WaitPolicy implements CannotExecuteHandler {
380
381	/**
382	* Constructs a <tt>WaitPolicy</tt>.
383	*/
384	public WaitPolicy() { }
385
386	public boolean cannotExecute(Runnable r, boolean isShutdown) {
387	if (!isShutdown) {
388	// FIXME: wait here
389	// FIXME: throw CannotExecuteException if interrupted
390	return false;
391	}
392	return true;
393	}
394	}
395
396	/**
397	* A handler for unexecutable tasks that silently discards these tasks.
398	*/
399	public class DiscardPolicy implements CannotExecuteHandler {
400
401	/**
402	* Constructs <tt>DiscardPolicy</tt>.
403	*/
404	public DiscardPolicy() { }
405
406	public boolean cannotExecute(Runnable r, boolean isShutdown) {
407	return true;
408	}
409	}
410
411	/**
412	* A handler for unexecutable tasks that discards the oldest unhandled request.
413	*/
414	public class DiscardOldestPolicy implements CannotExecuteHandler {
415
416	/**
417	* Constructs a <tt>DiscardOldestPolicy</tt>.
418	*/
419	public DiscardOldestPolicy() { }
420
421	public boolean cannotExecute(Runnable r, boolean isShutdown) {
422	if (!isShutdown) {
423	// FIXME: discard oldest here
424	return false;
425	}
426	return true;
427	}
428	}
429
430	/*
431	* Methods invoked during various points of execution, allowing fine-grained
432	* control and monitoring.
433	*/
434
435	/**
436	* Method invoked prior to executing the given Runnable in given
437	* thread. This method may be used to re-initialize ThreadLocals,
438	* or to perform logging.
439	*
440	* @param t the thread that will run task r.
441	* @param r the task that will be executed.
442	*/
443	protected void beforeExecute(Thread t, Runnable r) { }
444
445	/**
446	* Method invoked upon completion of execution of the given
447	* Runnable. If non-null, the Throwable is the uncaught exception
448	* that caused execution to terminate abruptly.
449	*
450	* @param r the runnable that has completed.
451	* @param t the exception that cause termination, or null if
452	* execution completed normally.
453	*/
454	protected void afterExecute(Runnable r, Throwable t) { }
455
456	/**
457	* Method invoked when the Executor has terminated. Default
458	* implementation does nothing.
459	*/
460	protected void terminated() { }
461	}