util/concurrent/Executors.java

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

package java.util.concurrent;

/**
 * A factory for the <tt>Executor</tt> classes defined in
 * <tt>java.util.concurrent</tt>.
 *
 * <p>An Executor is a framework for executing Runnables.  The
 * Executor manages queueing and scheduling of tasks, and creation and
 * teardown of threads.  Depending on which concrete Executor class is
 * being used, tasks may execute in a newly created thread, an
 * existing task-execution thread, or the thread calling execute(),
 * and may execute sequentially or concurrently.
 *
 * @since 1.5
 * @see Executor
 * @see ThreadedExecutor
 * @see Future
 *
 * @spec JSR-166
 * @revised $Date: 2003/02/28 03:53:49 $
 * @editor $Author: brian $
 */
public class Executors {

    /**
     * Creates a thread pool that reuses a fixed set of threads
     * operating off a shared unbounded queue.
     *
     * @param nThreads the number of threads in the pool
     * @return the newly created thread pool
     */
    public static ThreadedExecutor newFixedThreadPool(int nThreads) {
        return new ThreadPoolExecutor(nThreads, nThreads,
                                      0L, TimeUnit.MILLISECONDS,
                                      new LinkedBlockingQueue());
    }

    /**
     * Creates a thread pool that creates new threads as needed, but
     * will reuse previously constructed threads when they are
     * available.  These pools will typically improve the performance
     * of programs that execute many short-lived asynchronous tasks.
     * Calls to <tt>execute</tt> will reuse previously constructed
     * threads if available. If no existing thread is available, a new
     * thread will be created and added to the pool. Threads that have
     * not been used for sixty seconds are terminated and removed from
     * the cache. Thus, a pool that remains idle for long enough will
     * not consume any resources.
     *
     * @return the newly created thread pool
     */
    public static ThreadedExecutor newCachedThreadPool() {
        return new ThreadPoolExecutor(0, Integer.MAX_VALUE,
                                      60000, TimeUnit.MILLISECONDS,
                                      new SynchronousQueue());
    }

    /**
     * Creates a thread pool that reuses a limited pool of cached
     * threads.
     *
     * @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 queue the queue to use for holding tasks before they
     * are executed. This queue will hold only the <tt>Runnable</tt>
     * tasks submitted by the <tt>execute</tt> method.
     * @return the newly created thread pool
     * @throws IllegalArgumentException if minThreads, maxThreads, or
     * keepAliveTime less than zero, or if minThreads greater than
     * maxThreads.  
     * @throws NullPointerException if queue is null
     */
    public static ThreadedExecutor newThreadPool(int minThreads,
                                                   int maxThreads,
                                                   long keepAliveTime,
                                                   TimeUnit granularity,
                                                   BlockingQueue queue) {
        return new ThreadPoolExecutor(minThreads, maxThreads,
                                      keepAliveTime, granularity,
                                      queue);
    }

    /**
     * Creates an Executor that uses a single worker thread operating
     * off an unbounded queue. (Note however that if this single
     * thread terminates due to a failure during execution prior to
     * shutdown, a new one will take its place if needed to execute
     * subsequent tasks.)  Tasks are guaranteed to execute
     * sequentially, and no more than one task will be active at any
     * given time.
     *
     * @return the newly-created single-threaded Executor
     */
    public static SingleThreadedExecutor newSingleThreadExecutor() {
        return new SingleThreadedExecutor();
    }

    /**
     * Constructs a ScheduledExecutor.  A ScheduledExecutor is an
     * Executor which can schedule tasks to run at a given future
     * time, or to execute periodically.
     *
     * @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.
     * @return the newly created ScheduledExecutor
     */
    public static ScheduledExecutor newScheduledExecutor(int minThreads,
                                                         int maxThreads,
                                                         long keepAliveTime,
                                                         TimeUnit granularity) {
        return new ScheduledExecutor(minThreads, maxThreads,
                                     keepAliveTime, granularity);
    }

    /**
     * Executes a Runnable task and returns a Future representing that
     * task.
     *
     * @param executor the Executor to which the task will be submitted
     * @param task the task to submit
     * @param value the value which will become the return value of
     * the task upon task completion
     * @return a Future representing pending completion of the task
     * @throws CannotExecuteException if the task cannot be scheduled
     * for execution
     */
    public static <T> Future<T> execute(Executor executor, Runnable task, T value) {
        FutureTask<T> ftask = new FutureTask<T>(task, value);
        executor.execute(ftask);
        return ftask;
    }

    /**
     * Executes a value-returning task and returns a Future
     * representing the pending results of the task.
     *
     * @param executor the Executor to which the task will be submitted
     * @param task the task to submit
     * @return a Future representing pending completion of the task
     * @throws CannotExecuteException if task cannot be scheduled for execution
     */
    public static <T> Future<T> execute(Executor executor, Callable<T> task) {
        FutureTask<T> ftask = new FutureTask<T>(task);
        executor.execute(ftask);
        return ftask;
    }

    /**
     * Executes a Runnable task and blocks until it completes normally
     * or throws an exception.
     *
     * @param executor the Executor to which the task will be submitted
     * @param task the task to submit
     * @throws CannotExecuteException if task cannot be scheduled for execution
     */
    public static void invoke(Executor executor, Runnable task)
            throws ExecutionException, InterruptedException {
        FutureTask ftask = new FutureTask(task, Boolean.TRUE);
        executor.execute(ftask);
        ftask.get();
    }

    /**
     * Executes a value-returning task and blocks until it returns a
     * value or throws an exception.
     *
     * @param executor the Executor to which the task will be submitted
     * @param task the task to submit
     * @return a Future representing pending completion of the task
     * @throws CannotExecuteException if task cannot be scheduled for execution
     */
    public static <T> T invoke(Executor executor, Callable<T> task)
            throws ExecutionException, InterruptedException {
        FutureTask<T> ftask = new FutureTask<T>(task);
        executor.execute(ftask);
        return ftask.get();
    }
}
Revision:	1.1
Committed:	Wed May 14 21:30:46 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	* @(#)Executors.java
3	*/
4
5	package java.util.concurrent;
6
7	/**
8	* A factory for the <tt>Executor</tt> classes defined in
9	* <tt>java.util.concurrent</tt>.
10	*
11	* <p>An Executor is a framework for executing Runnables. The
12	* Executor manages queueing and scheduling of tasks, and creation and
13	* teardown of threads. Depending on which concrete Executor class is
14	* being used, tasks may execute in a newly created thread, an
15	* existing task-execution thread, or the thread calling execute(),
16	* and may execute sequentially or concurrently.
17	*
18	* @since 1.5
19	* @see Executor
20	* @see ThreadedExecutor
21	* @see Future
22	*
23	* @spec JSR-166
24	* @revised $Date: 2003/02/28 03:53:49 $
25	* @editor $Author: brian $
26	*/
27	public class Executors {
28
29	/**
30	* Creates a thread pool that reuses a fixed set of threads
31	* operating off a shared unbounded queue.
32	*
33	* @param nThreads the number of threads in the pool
34	* @return the newly created thread pool
35	*/
36	public static ThreadedExecutor newFixedThreadPool(int nThreads) {
37	return new ThreadPoolExecutor(nThreads, nThreads,
38	0L, TimeUnit.MILLISECONDS,
39	new LinkedBlockingQueue());
40	}
41
42	/**
43	* Creates a thread pool that creates new threads as needed, but
44	* will reuse previously constructed threads when they are
45	* available. These pools will typically improve the performance
46	* of programs that execute many short-lived asynchronous tasks.
47	* Calls to <tt>execute</tt> will reuse previously constructed
48	* threads if available. If no existing thread is available, a new
49	* thread will be created and added to the pool. Threads that have
50	* not been used for sixty seconds are terminated and removed from
51	* the cache. Thus, a pool that remains idle for long enough will
52	* not consume any resources.
53	*
54	* @return the newly created thread pool
55	*/
56	public static ThreadedExecutor newCachedThreadPool() {
57	return new ThreadPoolExecutor(0, Integer.MAX_VALUE,
58	60000, TimeUnit.MILLISECONDS,
59	new SynchronousQueue());
60	}
61
62	/**
63	* Creates a thread pool that reuses a limited pool of cached
64	* threads.
65	*
66	* @param minThreads the minimum number of threads to keep in the
67	* pool, even if they are idle.
68	* @param maxThreads the maximum number of threads to allow in the
69	* pool.
70	* @param keepAliveTime when the number of threads is greater than
71	* the minimum, this is the maximum time that excess idle threads
72	* will wait for new tasks before terminating.
73	* @param granularity the time unit for the keepAliveTime
74	* argument.
75	* @param queue the queue to use for holding tasks before they
76	* are executed. This queue will hold only the <tt>Runnable</tt>
77	* tasks submitted by the <tt>execute</tt> method.
78	* @return the newly created thread pool
79	* @throws IllegalArgumentException if minThreads, maxThreads, or
80	* keepAliveTime less than zero, or if minThreads greater than
81	* maxThreads.
82	* @throws NullPointerException if queue is null
83	*/
84	public static ThreadedExecutor newThreadPool(int minThreads,
85	int maxThreads,
86	long keepAliveTime,
87	TimeUnit granularity,
88	BlockingQueue queue) {
89	return new ThreadPoolExecutor(minThreads, maxThreads,
90	keepAliveTime, granularity,
91	queue);
92	}
93
94	/**
95	* Creates an Executor that uses a single worker thread operating
96	* off an unbounded queue. (Note however that if this single
97	* thread terminates due to a failure during execution prior to
98	* shutdown, a new one will take its place if needed to execute
99	* subsequent tasks.) Tasks are guaranteed to execute
100	* sequentially, and no more than one task will be active at any
101	* given time.
102	*
103	* @return the newly-created single-threaded Executor
104	*/
105	public static SingleThreadedExecutor newSingleThreadExecutor() {
106	return new SingleThreadedExecutor();
107	}
108
109	/**
110	* Constructs a ScheduledExecutor. A ScheduledExecutor is an
111	* Executor which can schedule tasks to run at a given future
112	* time, or to execute periodically.
113	*
114	* @param minThreads the minimum number of threads to keep in the
115	* pool, even if they are idle.
116	* @param maxThreads the maximum number of threads to allow in the
117	* pool.
118	* @param keepAliveTime when the number of threads is greater than
119	* the minimum, this is the maximum time that excess idle threads
120	* will wait for new tasks before terminating.
121	* @param granularity the time unit for the keepAliveTime
122	* argument.
123	* @return the newly created ScheduledExecutor
124	*/
125	public static ScheduledExecutor newScheduledExecutor(int minThreads,
126	int maxThreads,
127	long keepAliveTime,
128	TimeUnit granularity) {
129	return new ScheduledExecutor(minThreads, maxThreads,
130	keepAliveTime, granularity);
131	}
132
133	/**
134	* Executes a Runnable task and returns a Future representing that
135	* task.
136	*
137	* @param executor the Executor to which the task will be submitted
138	* @param task the task to submit
139	* @param value the value which will become the return value of
140	* the task upon task completion
141	* @return a Future representing pending completion of the task
142	* @throws CannotExecuteException if the task cannot be scheduled
143	* for execution
144	*/
145	public static <T> Future<T> execute(Executor executor, Runnable task, T value) {
146	FutureTask<T> ftask = new FutureTask<T>(task, value);
147	executor.execute(ftask);
148	return ftask;
149	}
150
151	/**
152	* Executes a value-returning task and returns a Future
153	* representing the pending results of the task.
154	*
155	* @param executor the Executor to which the task will be submitted
156	* @param task the task to submit
157	* @return a Future representing pending completion of the task
158	* @throws CannotExecuteException if task cannot be scheduled for execution
159	*/
160	public static <T> Future<T> execute(Executor executor, Callable<T> task) {
161	FutureTask<T> ftask = new FutureTask<T>(task);
162	executor.execute(ftask);
163	return ftask;
164	}
165
166	/**
167	* Executes a Runnable task and blocks until it completes normally
168	* or throws an exception.
169	*
170	* @param executor the Executor to which the task will be submitted
171	* @param task the task to submit
172	* @throws CannotExecuteException if task cannot be scheduled for execution
173	*/
174	public static void invoke(Executor executor, Runnable task)
175	throws ExecutionException, InterruptedException {
176	FutureTask ftask = new FutureTask(task, Boolean.TRUE);
177	executor.execute(ftask);
178	ftask.get();
179	}
180
181	/**
182	* Executes a value-returning task and blocks until it returns a
183	* value or throws an exception.
184	*
185	* @param executor the Executor to which the task will be submitted
186	* @param task the task to submit
187	* @return a Future representing pending completion of the task
188	* @throws CannotExecuteException if task cannot be scheduled for execution
189	*/
190	public static <T> T invoke(Executor executor, Callable<T> task)
191	throws ExecutionException, InterruptedException {
192	FutureTask<T> ftask = new FutureTask<T>(task);
193	executor.execute(ftask);
194	return ftask.get();
195	}
196	}