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 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
#	User	Rev	Content
1	tim	1.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			}