util/concurrent/Executors.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain. Use, modify, and
 * redistribute this code in any way without acknowledgement.
 */

package java.util.concurrent;
import java.util.*;

/**
 * Factory and utility methods 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 ExecutorService
 * @see Future
 *
 * @spec JSR-166
 * @revised $Date: 2003/05/27 18:14:40 $
 * @editor $Author: dl $
 */
public class Executors {

    /**
     * A wrapper class that exposes only the ExecutorService methods
     * of an implementation.
     */ 
    static private class DelegatedExecutorService implements ExecutorService {
        private final ExecutorService e;
        DelegatedExecutorService(ExecutorService executor) { e = executor; }
        public void execute(Runnable command) { e.execute(command); }
        public void shutdown() { e.shutdown(); }
        public List shutdownNow() { return e.shutdownNow(); }
        public boolean isShutdown() { return e.isShutdown(); }
        public boolean isTerminated() { return e.isTerminated(); }
        public boolean awaitTermination(long timeout, TimeUnit unit)
            throws InterruptedException {
            return e.awaitTermination(timeout, unit);
        }
    }

    /**
     * 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 ExecutorService newFixedThreadPool(int nThreads) {
        return new DelegatedExecutorService
            (new ThreadPoolExecutor(nThreads, nThreads,
                                    0L, TimeUnit.MILLISECONDS,
                                    new LinkedBlockingQueue<Runnable>()));
    }

    /**
     * Creates a thread pool that reuses a fixed set of threads
     * operating off a shared unbounded queue, using the provided
     * ThreadFactory to create new threads when needed.
     *
     * @param nThreads the number of threads in the pool
     * @param threadfactory the factory to use when creating new threads
     * @return the newly created thread pool
     */
    public static ExecutorService newFixedThreadPool(int nThreads, ThreadFactory threadFactory) {
        return new DelegatedExecutorService
            (new ThreadPoolExecutor(nThreads, nThreads,
                                    0L, TimeUnit.MILLISECONDS,
                                    new LinkedBlockingQueue<Runnable>(),
                                    threadFactory, null));
    }

    /**
     * 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 ExecutorService newSingleThreadExecutor() {
        return new DelegatedExecutorService
            (new ThreadPoolExecutor(1, 1, 
                                    0L, TimeUnit.MILLISECONDS,
                                    new LinkedBlockingQueue<Runnable>()));
    }

    /**
     * Creates an Executor that uses a single worker thread operating
     * off an unbounded queue, and uses the provided ThreadFactory to
     * create new threads when needed.
     * @param threadfactory the factory to use when creating new
     * threads
     *
     * @return the newly-created single-threaded Executor
     */
    public static ExecutorService newSingleThreadExecutor(ThreadFactory threadFactory) {
        return new DelegatedExecutorService
            (new ThreadPoolExecutor(1, 1, 
                                    0L, TimeUnit.MILLISECONDS,
                                    new LinkedBlockingQueue<Runnable>(),
                                    threadFactory, null));
    }

    /**
     * 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 ExecutorService newCachedThreadPool() {
        return new DelegatedExecutorService
            (new ThreadPoolExecutor(0, Integer.MAX_VALUE,
                                    60, TimeUnit.SECONDS,
                                    new SynchronousQueue<Runnable>()));
    }

    /**
     * Creates a thread pool that creates new threads as needed, but
     * will reuse previously constructed threads when they are
     * available, and uses the provided 
     * ThreadFactory to create new threads when needed.
     * @param threadfactory the factory to use when creating new threads
     * @return the newly created thread pool
     */
    public static ExecutorService newCachedThreadPool(ThreadFactory threadFactory) {
        return new DelegatedExecutorService
            (new ThreadPoolExecutor(0, Integer.MAX_VALUE,
                                    60, TimeUnit.SECONDS,
                                    new SynchronousQueue<Runnable>(),
                                    threadFactory, null));
    }

    /**
     * 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 unit the time unit for the keepAliveTime
     * argument.
     * @return the newly created ScheduledExecutor
     */
    //    public static ScheduledExecutor newScheduledExecutor(int minThreads,
    //                                                         int maxThreads,
    //                                                         long keepAliveTime,
    //                                                         TimeUnit unit) {
    //        return new ScheduledExecutor(minThreads, maxThreads,
    //                                     keepAliveTime, unit);
    //    }

    /**
     * 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.3
Committed:	Thu May 29 13:49:24 2003 UTC (21 years ago) by dl
Branch:	MAIN
CVS Tags:	JSR166_PRERELEASE_0_1
Changes since 1.2:	+8 -8 lines
Log Message:	Please the new generics compiler
#	User	Rev	Content
1	tim	1.1	/*
2	dl	1.2	* Written by Doug Lea with assistance from members of JCP JSR-166
3			* Expert Group and released to the public domain. Use, modify, and
4			* redistribute this code in any way without acknowledgement.
5	tim	1.1	*/
6
7			package java.util.concurrent;
8	dl	1.2	import java.util.*;
9	tim	1.1
10			/**
11	dl	1.2	* Factory and utility methods for the <tt>Executor</tt> classes
12			* defined in <tt>java.util.concurrent</tt>.
13	tim	1.1	*
14			* <p>An Executor is a framework for executing Runnables. The
15			* Executor manages queueing and scheduling of tasks, and creation and
16			* teardown of threads. Depending on which concrete Executor class is
17			* being used, tasks may execute in a newly created thread, an
18			* existing task-execution thread, or the thread calling execute(),
19			* and may execute sequentially or concurrently.
20			*
21			* @since 1.5
22			* @see Executor
23	dl	1.2	* @see ExecutorService
24	tim	1.1	* @see Future
25			*
26			* @spec JSR-166
27	dl	1.3	* @revised $Date: 2003/05/27 18:14:40 $
28			* @editor $Author: dl $
29	tim	1.1	*/
30			public class Executors {
31
32			/**
33	dl	1.2	* A wrapper class that exposes only the ExecutorService methods
34			* of an implementation.
35			*/
36			static private class DelegatedExecutorService implements ExecutorService {
37			private final ExecutorService e;
38			DelegatedExecutorService(ExecutorService executor) { e = executor; }
39			public void execute(Runnable command) { e.execute(command); }
40			public void shutdown() { e.shutdown(); }
41			public List shutdownNow() { return e.shutdownNow(); }
42			public boolean isShutdown() { return e.isShutdown(); }
43			public boolean isTerminated() { return e.isTerminated(); }
44			public boolean awaitTermination(long timeout, TimeUnit unit)
45			throws InterruptedException {
46			return e.awaitTermination(timeout, unit);
47			}
48			}
49
50			/**
51	tim	1.1	* Creates a thread pool that reuses a fixed set of threads
52			* operating off a shared unbounded queue.
53			*
54			* @param nThreads the number of threads in the pool
55			* @return the newly created thread pool
56			*/
57	dl	1.2	public static ExecutorService newFixedThreadPool(int nThreads) {
58			return new DelegatedExecutorService
59			(new ThreadPoolExecutor(nThreads, nThreads,
60			0L, TimeUnit.MILLISECONDS,
61	dl	1.3	new LinkedBlockingQueue<Runnable>()));
62	dl	1.2	}
63
64			/**
65			* Creates a thread pool that reuses a fixed set of threads
66			* operating off a shared unbounded queue, using the provided
67			* ThreadFactory to create new threads when needed.
68			*
69			* @param nThreads the number of threads in the pool
70			* @param threadfactory the factory to use when creating new threads
71			* @return the newly created thread pool
72			*/
73			public static ExecutorService newFixedThreadPool(int nThreads, ThreadFactory threadFactory) {
74			return new DelegatedExecutorService
75			(new ThreadPoolExecutor(nThreads, nThreads,
76			0L, TimeUnit.MILLISECONDS,
77	dl	1.3	new LinkedBlockingQueue<Runnable>(),
78	dl	1.2	threadFactory, null));
79			}
80
81			/**
82			* Creates an Executor that uses a single worker thread operating
83			* off an unbounded queue. (Note however that if this single
84			* thread terminates due to a failure during execution prior to
85			* shutdown, a new one will take its place if needed to execute
86			* subsequent tasks.) Tasks are guaranteed to execute
87			* sequentially, and no more than one task will be active at any
88			* given time.
89			*
90			* @return the newly-created single-threaded Executor
91			*/
92			public static ExecutorService newSingleThreadExecutor() {
93			return new DelegatedExecutorService
94			(new ThreadPoolExecutor(1, 1,
95			0L, TimeUnit.MILLISECONDS,
96	dl	1.3	new LinkedBlockingQueue<Runnable>()));
97	dl	1.2	}
98
99			/**
100			* Creates an Executor that uses a single worker thread operating
101			* off an unbounded queue, and uses the provided ThreadFactory to
102			* create new threads when needed.
103			* @param threadfactory the factory to use when creating new
104			* threads
105			*
106			* @return the newly-created single-threaded Executor
107			*/
108			public static ExecutorService newSingleThreadExecutor(ThreadFactory threadFactory) {
109			return new DelegatedExecutorService
110			(new ThreadPoolExecutor(1, 1,
111			0L, TimeUnit.MILLISECONDS,
112	dl	1.3	new LinkedBlockingQueue<Runnable>(),
113	dl	1.2	threadFactory, null));
114	tim	1.1	}
115
116			/**
117			* Creates a thread pool that creates new threads as needed, but
118			* will reuse previously constructed threads when they are
119			* available. These pools will typically improve the performance
120			* of programs that execute many short-lived asynchronous tasks.
121			* Calls to <tt>execute</tt> will reuse previously constructed
122			* threads if available. If no existing thread is available, a new
123			* thread will be created and added to the pool. Threads that have
124			* not been used for sixty seconds are terminated and removed from
125			* the cache. Thus, a pool that remains idle for long enough will
126			* not consume any resources.
127			*
128			* @return the newly created thread pool
129			*/
130	dl	1.2	public static ExecutorService newCachedThreadPool() {
131			return new DelegatedExecutorService
132			(new ThreadPoolExecutor(0, Integer.MAX_VALUE,
133			60, TimeUnit.SECONDS,
134	dl	1.3	new SynchronousQueue<Runnable>()));
135	tim	1.1	}
136
137			/**
138	dl	1.2	* Creates a thread pool that creates new threads as needed, but
139			* will reuse previously constructed threads when they are
140			* available, and uses the provided
141			* ThreadFactory to create new threads when needed.
142			* @param threadfactory the factory to use when creating new threads
143	tim	1.1	* @return the newly created thread pool
144			*/
145	dl	1.2	public static ExecutorService newCachedThreadPool(ThreadFactory threadFactory) {
146			return new DelegatedExecutorService
147			(new ThreadPoolExecutor(0, Integer.MAX_VALUE,
148			60, TimeUnit.SECONDS,
149	dl	1.3	new SynchronousQueue<Runnable>(),
150	dl	1.2	threadFactory, null));
151	tim	1.1	}
152
153			/**
154			* Constructs a ScheduledExecutor. A ScheduledExecutor is an
155			* Executor which can schedule tasks to run at a given future
156			* time, or to execute periodically.
157			*
158			* @param minThreads the minimum number of threads to keep in the
159			* pool, even if they are idle.
160			* @param maxThreads the maximum number of threads to allow in the
161			* pool.
162			* @param keepAliveTime when the number of threads is greater than
163			* the minimum, this is the maximum time that excess idle threads
164			* will wait for new tasks before terminating.
165	dl	1.2	* @param unit the time unit for the keepAliveTime
166	tim	1.1	* argument.
167			* @return the newly created ScheduledExecutor
168			*/
169	dl	1.2	// public static ScheduledExecutor newScheduledExecutor(int minThreads,
170			// int maxThreads,
171			// long keepAliveTime,
172			// TimeUnit unit) {
173			// return new ScheduledExecutor(minThreads, maxThreads,
174			// keepAliveTime, unit);
175			// }
176	tim	1.1
177			/**
178			* Executes a Runnable task and returns a Future representing that
179			* task.
180			*
181			* @param executor the Executor to which the task will be submitted
182			* @param task the task to submit
183			* @param value the value which will become the return value of
184			* the task upon task completion
185			* @return a Future representing pending completion of the task
186			* @throws CannotExecuteException if the task cannot be scheduled
187			* for execution
188			*/
189			public static <T> Future<T> execute(Executor executor, Runnable task, T value) {
190			FutureTask<T> ftask = new FutureTask<T>(task, value);
191			executor.execute(ftask);
192			return ftask;
193			}
194
195			/**
196			* Executes a value-returning task and returns a Future
197			* representing the pending results of the task.
198			*
199			* @param executor the Executor to which the task will be submitted
200			* @param task the task to submit
201			* @return a Future representing pending completion of the task
202			* @throws CannotExecuteException if task cannot be scheduled for execution
203			*/
204			public static <T> Future<T> execute(Executor executor, Callable<T> task) {
205			FutureTask<T> ftask = new FutureTask<T>(task);
206			executor.execute(ftask);
207			return ftask;
208			}
209
210			/**
211			* Executes a Runnable task and blocks until it completes normally
212			* or throws an exception.
213			*
214			* @param executor the Executor to which the task will be submitted
215			* @param task the task to submit
216			* @throws CannotExecuteException if task cannot be scheduled for execution
217			*/
218			public static void invoke(Executor executor, Runnable task)
219			throws ExecutionException, InterruptedException {
220			FutureTask ftask = new FutureTask(task, Boolean.TRUE);
221			executor.execute(ftask);
222			ftask.get();
223			}
224
225			/**
226			* Executes a value-returning task and blocks until it returns a
227			* value or throws an exception.
228			*
229			* @param executor the Executor to which the task will be submitted
230			* @param task the task to submit
231			* @return a Future representing pending completion of the task
232			* @throws CannotExecuteException if task cannot be scheduled for execution
233			*/
234			public static <T> T invoke(Executor executor, Callable<T> task)
235			throws ExecutionException, InterruptedException {
236			FutureTask<T> ftask = new FutureTask<T>(task);
237			executor.execute(ftask);
238			return ftask.get();
239			}
240			}