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>.
 *
 * @since 1.5
 * @see Executor
 * @see ExecutorService
 * @see Future
 *
 * @spec JSR-166
 * @revised $Date: 2003/08/19 15:04:57 $
 * @editor $Author: tim $
 * @author Doug Lea
 */
public class Executors {

    /**
     * A wrapper class that exposes only the ExecutorService methods
     * of an implementation.
     */
    private static 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. If any thread
     * terminates due to a failure during execution prior to shutdown,
     * a new one will take its place if needed to execute subsequent
     * tasks.
     *
     * @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));
    }

    /**
     * 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. This method is equivalent in effect to
     *<tt>new FixedThreadPool(1)</tt>.
     *
     * @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));
    }

    /**
     * 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. Note that pools with similar
     * properties but different details (for example, timeout parameters)
     * may be created using {@link ThreadPoolExecutor} constructors.
     *
     * @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));
    }

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

    /**
     * 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 RejectedExecutionException if 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 RejectedExecutionException 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 RejectedExecutionException if task cannot be scheduled
     * for execution
     */
    public static void invoke(Executor executor, Runnable task)
            throws ExecutionException, InterruptedException {
        FutureTask<Boolean> ftask = new FutureTask<Boolean>(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 RejectedExecutionException if task cannot be scheduled
     * for execution
     * @throws InterruptedException if interrupted while waiting for
     * completion
     */
    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();
    }

    
    /** Cannot instantiate. */
    private Executors() {}
}
Revision:	1.16
Committed:	Sun Aug 24 23:32:25 2003 UTC (20 years, 9 months ago) by dl
Branch:	MAIN
Changes since 1.15:	+11 -5 lines
Log Message:	Kill ScheduledExecutor Date methods; Documentation clarifications
#	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			* @since 1.5
15			* @see Executor
16	dl	1.2	* @see ExecutorService
17	tim	1.1	* @see Future
18			*
19			* @spec JSR-166
20	dl	1.16	* @revised $Date: 2003/08/19 15:04:57 $
21			* @editor $Author: tim $
22	dl	1.12	* @author Doug Lea
23	tim	1.1	*/
24			public class Executors {
25
26			/**
27	dl	1.2	* A wrapper class that exposes only the ExecutorService methods
28			* of an implementation.
29	tim	1.6	*/
30	jozart	1.11	private static class DelegatedExecutorService implements ExecutorService {
31	dl	1.2	private final ExecutorService e;
32			DelegatedExecutorService(ExecutorService executor) { e = executor; }
33			public void execute(Runnable command) { e.execute(command); }
34			public void shutdown() { e.shutdown(); }
35			public List shutdownNow() { return e.shutdownNow(); }
36			public boolean isShutdown() { return e.isShutdown(); }
37			public boolean isTerminated() { return e.isTerminated(); }
38			public boolean awaitTermination(long timeout, TimeUnit unit)
39			throws InterruptedException {
40			return e.awaitTermination(timeout, unit);
41			}
42			}
43
44			/**
45	tim	1.1	* Creates a thread pool that reuses a fixed set of threads
46	dl	1.16	* operating off a shared unbounded queue. If any thread
47			* terminates due to a failure during execution prior to shutdown,
48			* a new one will take its place if needed to execute subsequent
49			* tasks.
50	tim	1.1	*
51			* @param nThreads the number of threads in the pool
52			* @return the newly created thread pool
53			*/
54	dl	1.2	public static ExecutorService newFixedThreadPool(int nThreads) {
55			return new DelegatedExecutorService
56			(new ThreadPoolExecutor(nThreads, nThreads,
57			0L, TimeUnit.MILLISECONDS,
58	dl	1.3	new LinkedBlockingQueue<Runnable>()));
59	dl	1.2	}
60
61			/**
62			* Creates a thread pool that reuses a fixed set of threads
63			* operating off a shared unbounded queue, using the provided
64			* ThreadFactory to create new threads when needed.
65			*
66			* @param nThreads the number of threads in the pool
67	dl	1.12	* @param threadFactory the factory to use when creating new threads
68	dl	1.2	* @return the newly created thread pool
69			*/
70			public static ExecutorService newFixedThreadPool(int nThreads, ThreadFactory threadFactory) {
71			return new DelegatedExecutorService
72			(new ThreadPoolExecutor(nThreads, nThreads,
73			0L, TimeUnit.MILLISECONDS,
74	dl	1.3	new LinkedBlockingQueue<Runnable>(),
75	dl	1.14	threadFactory));
76	dl	1.2	}
77
78			/**
79			* Creates an Executor that uses a single worker thread operating
80			* off an unbounded queue. (Note however that if this single
81			* thread terminates due to a failure during execution prior to
82			* shutdown, a new one will take its place if needed to execute
83			* subsequent tasks.) Tasks are guaranteed to execute
84			* sequentially, and no more than one task will be active at any
85	dl	1.16	* given time. This method is equivalent in effect to
86			*<tt>new FixedThreadPool(1)</tt>.
87	dl	1.2	*
88			* @return the newly-created single-threaded Executor
89			*/
90			public static ExecutorService newSingleThreadExecutor() {
91			return new DelegatedExecutorService
92	tim	1.6	(new ThreadPoolExecutor(1, 1,
93	dl	1.2	0L, TimeUnit.MILLISECONDS,
94	dl	1.3	new LinkedBlockingQueue<Runnable>()));
95	dl	1.2	}
96
97			/**
98			* Creates an Executor that uses a single worker thread operating
99			* off an unbounded queue, and uses the provided ThreadFactory to
100			* create new threads when needed.
101	dl	1.12	* @param threadFactory the factory to use when creating new
102	dl	1.2	* threads
103			*
104			* @return the newly-created single-threaded Executor
105			*/
106			public static ExecutorService newSingleThreadExecutor(ThreadFactory threadFactory) {
107			return new DelegatedExecutorService
108	tim	1.6	(new ThreadPoolExecutor(1, 1,
109	dl	1.2	0L, TimeUnit.MILLISECONDS,
110	dl	1.3	new LinkedBlockingQueue<Runnable>(),
111	dl	1.14	threadFactory));
112	tim	1.1	}
113
114			/**
115			* Creates a thread pool that creates new threads as needed, but
116			* will reuse previously constructed threads when they are
117			* available. These pools will typically improve the performance
118			* of programs that execute many short-lived asynchronous tasks.
119			* Calls to <tt>execute</tt> will reuse previously constructed
120			* threads if available. If no existing thread is available, a new
121			* thread will be created and added to the pool. Threads that have
122			* not been used for sixty seconds are terminated and removed from
123			* the cache. Thus, a pool that remains idle for long enough will
124	dl	1.16	* not consume any resources. Note that pools with similar
125			* properties but different details (for example, timeout parameters)
126			* may be created using {@link ThreadPoolExecutor} constructors.
127	tim	1.1	*
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	tim	1.6	* available, and uses the provided
141	dl	1.2	* ThreadFactory to create new threads when needed.
142	dl	1.12	* @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.14	threadFactory));
151	tim	1.1	}
152
153			/**
154	tim	1.15	* Executes a Runnable task and returns a Cancellable representing that
155			* task.
156			*
157			* @param executor the Executor to which the task will be submitted
158			* @param task the task to submit
159			* @return a Cancellable representing pending completion of the task
160			* @throws RejectedExecutionException if task cannot be scheduled
161			* for execution
162			*/
163			public static Cancellable execute(Executor executor, Runnable task) {
164			FutureTask<Boolean> ftask = new FutureTask<Boolean>(task, Boolean.TRUE);
165			executor.execute(ftask);
166			return ftask;
167			}
168
169			/**
170	tim	1.1	* Executes a Runnable task and returns a Future representing that
171			* task.
172			*
173			* @param executor the Executor to which the task will be submitted
174			* @param task the task to submit
175			* @param value the value which will become the return value of
176			* the task upon task completion
177	dl	1.5	* @return a Future representing pending completion of the task
178	jozart	1.9	* @throws RejectedExecutionException if task cannot be scheduled
179	tim	1.1	* for execution
180			*/
181	dl	1.5	public static <T> Future<T> execute(Executor executor, Runnable task, T value) {
182	dl	1.10	FutureTask<T> ftask = new FutureTask<T>(task, value);
183	tim	1.1	executor.execute(ftask);
184			return ftask;
185			}
186
187			/**
188			* Executes a value-returning task and returns a Future
189			* representing the pending results of the task.
190			*
191			* @param executor the Executor to which the task will be submitted
192			* @param task the task to submit
193			* @return a Future representing pending completion of the task
194	jozart	1.9	* @throws RejectedExecutionException if task cannot be scheduled
195			* for execution
196	tim	1.1	*/
197	tim	1.15	public static <T> Future<T> execute(Executor executor, Callable<T> task) {
198	dl	1.10	FutureTask<T> ftask = new FutureTask<T>(task);
199	tim	1.1	executor.execute(ftask);
200			return ftask;
201			}
202
203			/**
204			* Executes a Runnable task and blocks until it completes normally
205			* or throws an exception.
206			*
207			* @param executor the Executor to which the task will be submitted
208			* @param task the task to submit
209	jozart	1.9	* @throws RejectedExecutionException if task cannot be scheduled
210			* for execution
211	tim	1.1	*/
212			public static void invoke(Executor executor, Runnable task)
213			throws ExecutionException, InterruptedException {
214	tim	1.13	FutureTask<Boolean> ftask = new FutureTask<Boolean>(task, Boolean.TRUE);
215	tim	1.1	executor.execute(ftask);
216			ftask.get();
217			}
218
219			/**
220			* Executes a value-returning task and blocks until it returns a
221			* value or throws an exception.
222			*
223			* @param executor the Executor to which the task will be submitted
224			* @param task the task to submit
225			* @return a Future representing pending completion of the task
226	jozart	1.9	* @throws RejectedExecutionException if task cannot be scheduled
227			* for execution
228	dl	1.12	* @throws InterruptedException if interrupted while waiting for
229			* completion
230	tim	1.1	*/
231			public static <T> T invoke(Executor executor, Callable<T> task)
232			throws ExecutionException, InterruptedException {
233			FutureTask<T> ftask = new FutureTask<T>(task);
234			executor.execute(ftask);
235			return ftask.get();
236	tim	1.6	}
237
238	tim	1.15
239			/** Cannot instantiate. */
240			private Executors() {}
241	tim	1.1	}