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 {@link Runnable} 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.  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 {
 *     final Queue&lt;Runnable&gt; tasks = new LinkedBlockingQueue&lt;Runnable&gt;();
 *     final 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 this package
 * implement {@link ExecutorService}, which is a more extensive
 * interface.  The {@link ThreadPoolExecutor} class provides an
 * extensible thread pool implementation. The {@link Executors} class
 * provides convenient factory methods for these Executors.
 *
 * @since 1.5
 * @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 this task cannot be
     * accepted for execution.
     * @throws NullPointerException if command is null
     */
    void execute(Runnable command);
}
Revision:	1.14
Committed:	Wed Dec 10 16:24:52 2003 UTC (20 years, 5 months ago) by tim
Branch:	MAIN
Changes since 1.13:	+2 -2 lines
Log Message:	Made fields final in sample code, type of tasks now Queue<Runnable>
#	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
9			/**
10	dl	1.11	* An object that executes submitted {@link Runnable} tasks. This
11			* interface provides a way of decoupling task submission from the
12			* mechanics of how each task will be run, including details of thread
13			* use, scheduling, etc. In the simplest case, an executor can run
14			* the submitted task immediately in the caller's thread:
15	tim	1.1	*
16			* <pre>
17			* class DirectExecutor implements Executor {
18			* public void execute(Runnable r) {
19			* r.run();
20			* }
21			* }</pre>
22			*
23			* However, tasks are typically executed in a different thread than
24	jozart	1.5	* the caller's thread. The executor below spawns a new thread for
25			* each task.
26	tim	1.1	*
27			* <pre>
28			* class ThreadPerTaskExecutor implements Executor {
29			* public void execute(Runnable r) {
30			* new Thread(r).start();
31			* }
32			* }</pre>
33			*
34	dl	1.10	* Most <tt>Executor</tt> implementations will impose some sort of
35			* limitation on how and when tasks are scheduled. The executor below
36			* serializes the submission of tasks to a second executor,
37			* illustrating a composite executor.
38	tim	1.1	*
39			* <pre>
40			* class SerialExecutor implements Executor {
41	tim	1.14	* final Queue<Runnable> tasks = new LinkedBlockingQueue<Runnable>();
42			* final Executor executor;
43	tim	1.1	* 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	dl	1.10	* The <tt>Executor</tt> implementations provided in this package
72			* implement {@link ExecutorService}, which is a more extensive
73			* interface. The {@link ThreadPoolExecutor} class provides an
74			* extensible thread pool implementation. The {@link Executors} class
75			* provides convenient factory methods for these Executors.
76	tim	1.1	*
77			* @since 1.5
78	dl	1.7	* @author Doug Lea
79	tim	1.1	*/
80			public interface Executor {
81
82			/**
83			* Executes the given command at some time in the future. The command
84			* may execute in a new thread, in a pooled thread, or in the calling
85			* thread, at the discretion of the <tt>Executor</tt> implementation.
86			*
87	jozart	1.6	* @param command the runnable task
88	dl	1.10	* @throws RejectedExecutionException if this task cannot be
89			* accepted for execution.
90	dl	1.12	* @throws NullPointerException if command is null
91	tim	1.1	*/
92	jozart	1.6	void execute(Runnable command);
93	tim	1.1	}