util/concurrent/Executor.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;

/**
 * An object that executes submitted tasks. This interface provides a
 * way of decoupling task submission from the mechanics of how each
 * task will be run, including details of thread use, scheduling, etc.
 *
 * <p>In the simplest case, an executor can run the submitted task immediately
 * in the caller's thread:
 *
 * <pre>
 * class DirectExecutor implements Executor {
 *     public void execute(Runnable r) {
 *         r.run();
 *     }
 * }</pre>
 *
 * However, tasks are typically executed in a different thread than
 * the caller's thread.  The executor below spawns a new thread for
 * each task.
 *
 * <pre>
 * class ThreadPerTaskExecutor implements Executor {
 *     public void execute(Runnable r) {
 *         new Thread(r).start();
 *     }
 * }</pre>
 *
 * Most <tt>Executor</tt> implementations will impose some sort of limitation
 * on how and when tasks are scheduled.  The executor below serializes the
 * submission of tasks to a second executor, illustrating a composite executor.
 *
 * <pre>
 * class SerialExecutor implements Executor {
 *     LinkedBlockingQueue tasks = new LinkedBlockingQueue<Runnable>();
 *     Executor executor;
 *     Runnable active;
 *
 *     SerialExecutor(Executor executor) {
 *         this.executor = executor;
 *     }
 *
 *     public synchronized void execute(final Runnable r) {
 *         tasks.offer(new Runnable() {
 *             public void run() {
 *                 try {
 *                     r.run();
 *                 } finally {
 *                     scheduleNext();
 *                 }
 *             }
 *         });
 *         if (active == null) {
 *             scheduleNext();
 *         }
 *     }
 *
 *     protected synchronized void scheduleNext() {
 *         if ((active = tasks.poll()) != null) {
 *             executor.execute(active);
 *         }
 *     }
 * }</pre>
 *
 * The <tt>Executor</tt> implementations provided in
 * <tt>java.util.concurrent</tt> implement <tt>ExecutorService</tt>,
 * which is a more extensive interface.  For more advanced users, the
 * <tt>ThreadPoolExecutor</tt> class provides a powerful, extensible
 * thread pool implementation. The <tt>Executors</tt> class provides
 * convenient factory methods for these executors.
 *
 * @since 1.5
 * @see Executors
 * @see FutureTask
 *
 * @spec JSR-166
 * @revised $Date: 2003/06/24 14:34:47 $
 * @editor $Author: dl $
 * @author Doug Lea
 */
public interface Executor {

    /**
     * Executes the given command at some time in the future.  The command
     * may execute in a new thread, in a pooled thread, or in the calling
     * thread, at the discretion of the <tt>Executor</tt> implementation.
     *
     * @param command the runnable task
     * @throws RejectedExecutionException if task cannot be submitted for
     * execution
     */
    void execute(Runnable command);
}
Revision:	1.8
Committed:	Thu Jun 26 10:47:35 2003 UTC (20 years, 11 months ago) by dl
Branch:	MAIN
CVS Tags:	JSR166_PRELIMINARY_TEST_RELEASE_2
Changes since 1.7:	+3 -3 lines
Log Message:	Added "Concurrent" prefixes
#	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
9	/**
10	* An object that executes submitted tasks. This interface provides a
11	* way of decoupling task submission from the mechanics of how each
12	* task will be run, including details of thread use, scheduling, etc.
13	*
14	* <p>In the simplest case, an executor can run the submitted task immediately
15	* in the caller's thread:
16	*
17	* <pre>
18	* class DirectExecutor implements Executor {
19	* public void execute(Runnable r) {
20	* r.run();
21	* }
22	* }</pre>
23	*
24	* However, tasks are typically executed in a different thread than
25	* the caller's thread. The executor below spawns a new thread for
26	* each task.
27	*
28	* <pre>
29	* class ThreadPerTaskExecutor implements Executor {
30	* public void execute(Runnable r) {
31	* new Thread(r).start();
32	* }
33	* }</pre>
34	*
35	* Most <tt>Executor</tt> implementations will impose some sort of limitation
36	* on how and when tasks are scheduled. The executor below serializes the
37	* submission of tasks to a second executor, illustrating a composite executor.
38	*
39	* <pre>
40	* class SerialExecutor implements Executor {
41	* LinkedBlockingQueue tasks = new LinkedBlockingQueue<Runnable>();
42	* Executor executor;
43	* Runnable active;
44	*
45	* SerialExecutor(Executor executor) {
46	* this.executor = executor;
47	* }
48	*
49	* public synchronized void execute(final Runnable r) {
50	* tasks.offer(new Runnable() {
51	* public void run() {
52	* try {
53	* r.run();
54	* } finally {
55	* scheduleNext();
56	* }
57	* }
58	* });
59	* if (active == null) {
60	* scheduleNext();
61	* }
62	* }
63	*
64	* protected synchronized void scheduleNext() {
65	* if ((active = tasks.poll()) != null) {
66	* executor.execute(active);
67	* }
68	* }
69	* }</pre>
70	*
71	* The <tt>Executor</tt> implementations provided in
72	* <tt>java.util.concurrent</tt> implement <tt>ExecutorService</tt>,
73	* which is a more extensive interface. For more advanced users, the
74	* <tt>ThreadPoolExecutor</tt> class provides a powerful, extensible
75	* thread pool implementation. The <tt>Executors</tt> class provides
76	* convenient factory methods for these executors.
77	*
78	* @since 1.5
79	* @see Executors
80	* @see FutureTask
81	*
82	* @spec JSR-166
83	* @revised $Date: 2003/06/24 14:34:47 $
84	* @editor $Author: dl $
85	* @author Doug Lea
86	*/
87	public interface Executor {
88
89	/**
90	* Executes the given command at some time in the future. The command
91	* may execute in a new thread, in a pooled thread, or in the calling
92	* thread, at the discretion of the <tt>Executor</tt> implementation.
93	*
94	* @param command the runnable task
95	* @throws RejectedExecutionException if task cannot be submitted for
96	* execution
97	*/
98	void execute(Runnable command);
99	}