1 /*
2  * Written by Doug Lea with assistance from members of JCP JSR-166
3  * Expert Group and released to the public domain, as explained at
4  * http://creativecommons.org/publicdomain/zero/1.0/
5  */
6 
7 package java.util.concurrent;
8 
9 /**
10  * 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.  An {@code Executor} is normally used
14  * instead of explicitly creating threads. For example, rather than
15  * invoking {@code new Thread(new RunnableTask()).start()} for each
16  * of a set of tasks, you might use:
17  *
18  * <pre> {@code
19  * Executor executor = anExecutor();
20  * executor.execute(new RunnableTask1());
21  * executor.execute(new RunnableTask2());
22  * ...}</pre>
23  *
24  * However, the {@code Executor} interface does not strictly require
25  * that execution be asynchronous. In the simplest case, an executor
26  * can run the submitted task immediately in the caller's thread:
27  *
28  * <pre> {@code
29  * class DirectExecutor implements Executor {
30  *   public void execute(Runnable r) {
31  *     r.run();
32  *   }
33  * }}</pre>
34  *
35  * More typically, tasks are executed in some thread other than the
36  * caller's thread.  The executor below spawns a new thread for each
37  * task.
38  *
39  * <pre> {@code
40  * class ThreadPerTaskExecutor implements Executor {
41  *   public void execute(Runnable r) {
42  *     new Thread(r).start();
43  *   }
44  * }}</pre>
45  *
46  * Many {@code Executor} implementations impose some sort of
47  * limitation on how and when tasks are scheduled.  The executor below
48  * serializes the submission of tasks to a second executor,
49  * illustrating a composite executor.
50  *
51  * <pre> {@code
52  * class SerialExecutor implements Executor {
53  *   final Queue<Runnable> tasks = new ArrayDeque<>();
54  *   final Executor executor;
55  *   Runnable active;
56  *
57  *   SerialExecutor(Executor executor) {
58  *     this.executor = executor;
59  *   }
60  *
61  *   public synchronized void execute(final Runnable r) {
62  *     tasks.add(new Runnable() {
63  *       public void run() {
64  *         try {
65  *           r.run();
66  *         } finally {
67  *           scheduleNext();
68  *         }
69  *       }
70  *     });
71  *     if (active == null) {
72  *       scheduleNext();
73  *     }
74  *   }
75  *
76  *   protected synchronized void scheduleNext() {
77  *     if ((active = tasks.poll()) != null) {
78  *       executor.execute(active);
79  *     }
80  *   }
81  * }}</pre>
82  *
83  * The {@code Executor} implementations provided in this package
84  * implement {@link ExecutorService}, which is a more extensive
85  * interface.  The {@link ThreadPoolExecutor} class provides an
86  * extensible thread pool implementation. The {@link Executors} class
87  * provides convenient factory methods for these Executors.
88  *
89  * <p>Memory consistency effects: Actions in a thread prior to
90  * submitting a {@code Runnable} object to an {@code Executor}
91  * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
92  * its execution begins, perhaps in another thread.
93  *
94  * @since 1.5
95  * @author Doug Lea
96  */
97 public interface Executor {
98 
99     /**
100      * Executes the given command at some time in the future.  The command
101      * may execute in a new thread, in a pooled thread, or in the calling
102      * thread, at the discretion of the {@code Executor} implementation.
103      *
104      * @param command the runnable task
105      * @throws RejectedExecutionException if this task cannot be
106      * accepted for execution
107      * @throws NullPointerException if command is null
108      */
execute(Runnable command)109     void execute(Runnable command);
110 }
111