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