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
     */
    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.18
Committed:	Mon Sep 1 14:00:25 2003 UTC (20 years, 9 months ago) by dl
Branch:	MAIN
Changes since 1.17:	+1 -1 lines
Log Message:	Fix javadoc typos
#	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.18	* Factory and utility methods for {@link Executor}, {@link
12	dl	1.17	* ExecutorService}, {@link Future}, and {@link Cancellable} classes
13			* defined in this package.
14	tim	1.1	*
15			* @since 1.5
16	dl	1.12	* @author Doug Lea
17	tim	1.1	*/
18			public class Executors {
19
20			/**
21	dl	1.2	* A wrapper class that exposes only the ExecutorService methods
22			* of an implementation.
23	tim	1.6	*/
24	jozart	1.11	private static class DelegatedExecutorService implements ExecutorService {
25	dl	1.2	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	tim	1.1	* Creates a thread pool that reuses a fixed set of threads
40	dl	1.16	* 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	tim	1.1	*
45			* @param nThreads the number of threads in the pool
46			* @return the newly created thread pool
47			*/
48	dl	1.2	public static ExecutorService newFixedThreadPool(int nThreads) {
49			return new DelegatedExecutorService
50			(new ThreadPoolExecutor(nThreads, nThreads,
51			0L, TimeUnit.MILLISECONDS,
52	dl	1.3	new LinkedBlockingQueue<Runnable>()));
53	dl	1.2	}
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	dl	1.12	* @param threadFactory the factory to use when creating new threads
62	dl	1.2	* @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	dl	1.3	new LinkedBlockingQueue<Runnable>(),
69	dl	1.14	threadFactory));
70	dl	1.2	}
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	dl	1.16	* given time. This method is equivalent in effect to
80			*<tt>new FixedThreadPool(1)</tt>.
81	dl	1.2	*
82			* @return the newly-created single-threaded Executor
83			*/
84			public static ExecutorService newSingleThreadExecutor() {
85			return new DelegatedExecutorService
86	tim	1.6	(new ThreadPoolExecutor(1, 1,
87	dl	1.2	0L, TimeUnit.MILLISECONDS,
88	dl	1.3	new LinkedBlockingQueue<Runnable>()));
89	dl	1.2	}
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	dl	1.12	* @param threadFactory the factory to use when creating new
96	dl	1.2	* threads
97			*
98			* @return the newly-created single-threaded Executor
99			*/
100			public static ExecutorService newSingleThreadExecutor(ThreadFactory threadFactory) {
101			return new DelegatedExecutorService
102	tim	1.6	(new ThreadPoolExecutor(1, 1,
103	dl	1.2	0L, TimeUnit.MILLISECONDS,
104	dl	1.3	new LinkedBlockingQueue<Runnable>(),
105	dl	1.14	threadFactory));
106	tim	1.1	}
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	dl	1.16	* 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	tim	1.1	*
122			* @return the newly created thread pool
123			*/
124	dl	1.2	public static ExecutorService newCachedThreadPool() {
125			return new DelegatedExecutorService
126			(new ThreadPoolExecutor(0, Integer.MAX_VALUE,
127			60, TimeUnit.SECONDS,
128	dl	1.3	new SynchronousQueue<Runnable>()));
129	tim	1.1	}
130
131			/**
132	dl	1.2	* Creates a thread pool that creates new threads as needed, but
133			* will reuse previously constructed threads when they are
134	tim	1.6	* available, and uses the provided
135	dl	1.2	* ThreadFactory to create new threads when needed.
136	dl	1.12	* @param threadFactory the factory to use when creating new threads
137	tim	1.1	* @return the newly created thread pool
138			*/
139	dl	1.2	public static ExecutorService newCachedThreadPool(ThreadFactory threadFactory) {
140			return new DelegatedExecutorService
141			(new ThreadPoolExecutor(0, Integer.MAX_VALUE,
142			60, TimeUnit.SECONDS,
143	dl	1.3	new SynchronousQueue<Runnable>(),
144	dl	1.14	threadFactory));
145	tim	1.1	}
146
147			/**
148	tim	1.15	* 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	tim	1.1	* 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	dl	1.5	* @return a Future representing pending completion of the task
172	jozart	1.9	* @throws RejectedExecutionException if task cannot be scheduled
173	tim	1.1	* for execution
174			*/
175	dl	1.5	public static <T> Future<T> execute(Executor executor, Runnable task, T value) {
176	dl	1.10	FutureTask<T> ftask = new FutureTask<T>(task, value);
177	tim	1.1	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	jozart	1.9	* @throws RejectedExecutionException if task cannot be scheduled
189			* for execution
190	tim	1.1	*/
191	tim	1.15	public static <T> Future<T> execute(Executor executor, Callable<T> task) {
192	dl	1.10	FutureTask<T> ftask = new FutureTask<T>(task);
193	tim	1.1	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	jozart	1.9	* @throws RejectedExecutionException if task cannot be scheduled
204			* for execution
205	tim	1.1	*/
206			public static void invoke(Executor executor, Runnable task)
207			throws ExecutionException, InterruptedException {
208	tim	1.13	FutureTask<Boolean> ftask = new FutureTask<Boolean>(task, Boolean.TRUE);
209	tim	1.1	executor.execute(ftask);
210			ftask.get();
211			}
212
213			/**
214			* Executes a value-returning task and blocks until it returns a
215			* value or throws an exception.
216			*
217			* @param executor the Executor to which the task will be submitted
218			* @param task the task to submit
219			* @return a Future representing pending completion of the task
220	jozart	1.9	* @throws RejectedExecutionException if task cannot be scheduled
221			* for execution
222	dl	1.12	* @throws InterruptedException if interrupted while waiting for
223			* completion
224	tim	1.1	*/
225			public static <T> T invoke(Executor executor, Callable<T> task)
226			throws ExecutionException, InterruptedException {
227			FutureTask<T> ftask = new FutureTask<T>(task);
228			executor.execute(ftask);
229			return ftask.get();
230	tim	1.6	}
231
232	tim	1.15
233			/** Cannot instantiate. */
234			private Executors() {}
235	tim	1.1	}