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 could 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 example below shows a simple Executor
 * which spawns a new thread for each task, but most Executor
 * implementations will impose some sort of limitation on how and when
 * tasks are scheduled:
 *
 * <pre>
 * class ThreadPerTaskExecutor implements Executor {
 *     public void execute(Runnable r) {
 *         new Thread(r).start();
 *     }
 * }</pre>
 *
 * The Executor example below uses a second Executor as part of its
 * implementation, and acts as a gatekeeper, submitting tasks to the
 * underlying Executor sequentially, one at a time:
 *
 * <pre>
 * class SerialExecutor implements Executor {
 *     LinkedQueue tasks = new LinkedQueue<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/05/27 18:14:40 $
 * @editor $Author: dl $
 */
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 CannotExecuteException if command cannot be submitted for
     * execution
     */
    void execute(Runnable command);
}
Revision:	1.3
Committed:	Wed Jun 4 11:34:19 2003 UTC (21 years ago) by dl
Branch:	MAIN
Changes since 1.2:	+2 -25 lines
Log Message:	Minor documentation updates Remove remove(task) from ExecutorService, Add removablity to ScheduledExecutor tasks, Revert Executors.execute to return FutureTask
#	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 could run the submitted task
15	* immediately 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 example below shows a simple Executor
26	* which spawns a new thread for each task, but most Executor
27	* implementations will impose some sort of limitation on how and when
28	* tasks are scheduled:
29	*
30	* <pre>
31	* class ThreadPerTaskExecutor implements Executor {
32	* public void execute(Runnable r) {
33	* new Thread(r).start();
34	* }
35	* }</pre>
36	*
37	* The Executor example below uses a second Executor as part of its
38	* implementation, and acts as a gatekeeper, submitting tasks to the
39	* underlying Executor sequentially, one at a time:
40	*
41	* <pre>
42	* class SerialExecutor implements Executor {
43	* LinkedQueue tasks = new LinkedQueue<Runnable>();
44	* Executor executor;
45	* Runnable active;
46	*
47	* SerialExecutor(Executor executor) {
48	* this.executor = executor;
49	* }
50	*
51	* public synchronized void execute(final Runnable r) {
52	* tasks.offer(new Runnable() {
53	* public void run() {
54	* try {
55	* r.run();
56	* } finally {
57	* scheduleNext();
58	* }
59	* }
60	* });
61	* if (active == null) {
62	* scheduleNext();
63	* }
64	* }
65	*
66	* protected synchronized void scheduleNext() {
67	* if ((active = tasks.poll()) != null) {
68	* executor.execute(active);
69	* }
70	* }
71	* }</pre>
72	*
73	* The <tt>Executor</tt> implementations provided in
74	* <tt>java.util.concurrent</tt> implement <tt>ExecutorService</tt>,
75	* which is a more extensive interface. For more advanced users, the
76	* <tt>ThreadPoolExecutor</tt> class provides a powerful, extensible
77	* thread pool implementation. The <tt>Executors</tt> class provides
78	* convenient factory methods for these executors.
79	*
80	* @since 1.5
81	* @see Executors
82	* @see FutureTask
83	*
84	* @spec JSR-166
85	* @revised $Date: 2003/05/27 18:14:40 $
86	* @editor $Author: dl $
87	*/
88	public interface Executor {
89
90	/**
91	* Executes the given command at some time in the future. The command
92	* may execute in a new thread, in a pooled thread, or in the calling
93	* thread, at the discretion of the <tt>Executor</tt> implementation.
94	*
95	* @param command the runnable task
96	* @throws CannotExecuteException if command cannot be submitted for
97	* execution
98	*/
99	void execute(Runnable command);
100	}