View Javadoc
1   /*
2    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3    *
4    * This code is free software; you can redistribute it and/or modify it
5    * under the terms of the GNU General Public License version 2 only, as
6    * published by the Free Software Foundation.  Oracle designates this
7    * particular file as subject to the "Classpath" exception as provided
8    * by Oracle in the LICENSE file that accompanied this code.
9    *
10   * This code is distributed in the hope that it will be useful, but WITHOUT
11   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
13   * version 2 for more details (a copy is included in the LICENSE file that
14   * accompanied this code).
15   *
16   * You should have received a copy of the GNU General Public License version
17   * 2 along with this work; if not, write to the Free Software Foundation,
18   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19   *
20   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21   * or visit www.oracle.com if you need additional information or have any
22   * questions.
23   */
24  
25  /*
26   * This file is available under and governed by the GNU General Public
27   * License version 2 only, as published by the Free Software Foundation.
28   * However, the following notice accompanied the original version of this
29   * file:
30   *
31   * Written by Doug Lea with assistance from members of JCP JSR-166
32   * Expert Group and released to the public domain, as explained at
33   * http://creativecommons.org/publicdomain/zero/1.0/
34   */
35  
36  package java.util.concurrent;
37  
38  /**
39   * An object that executes submitted {@link Runnable} tasks. This
40   * interface provides a way of decoupling task submission from the
41   * mechanics of how each task will be run, including details of thread
42   * use, scheduling, etc.  An {@code Executor} is normally used
43   * instead of explicitly creating threads. For example, rather than
44   * invoking {@code new Thread(new(RunnableTask())).start()} for each
45   * of a set of tasks, you might use:
46   *
47   * <pre>
48   * Executor executor = <em>anExecutor</em>;
49   * executor.execute(new RunnableTask1());
50   * executor.execute(new RunnableTask2());
51   * ...
52   * </pre>
53   *
54   * However, the {@code Executor} interface does not strictly
55   * require that execution be asynchronous. In the simplest case, an
56   * executor can run the submitted task immediately in the caller's
57   * thread:
58   *
59   *  <pre> {@code
60   * class DirectExecutor implements Executor {
61   *   public void execute(Runnable r) {
62   *     r.run();
63   *   }
64   * }}</pre>
65   *
66   * More typically, tasks are executed in some thread other
67   * than the caller's thread.  The executor below spawns a new thread
68   * for each task.
69   *
70   *  <pre> {@code
71   * class ThreadPerTaskExecutor implements Executor {
72   *   public void execute(Runnable r) {
73   *     new Thread(r).start();
74   *   }
75   * }}</pre>
76   *
77   * Many {@code Executor} implementations impose some sort of
78   * limitation on how and when tasks are scheduled.  The executor below
79   * serializes the submission of tasks to a second executor,
80   * illustrating a composite executor.
81   *
82   *  <pre> {@code
83   * class SerialExecutor implements Executor {
84   *   final Queue<Runnable> tasks = new ArrayDeque<Runnable>();
85   *   final Executor executor;
86   *   Runnable active;
87   *
88   *   SerialExecutor(Executor executor) {
89   *     this.executor = executor;
90   *   }
91   *
92   *   public synchronized void execute(final Runnable r) {
93   *     tasks.offer(new Runnable() {
94   *       public void run() {
95   *         try {
96   *           r.run();
97   *         } finally {
98   *           scheduleNext();
99   *         }
100  *       }
101  *     });
102  *     if (active == null) {
103  *       scheduleNext();
104  *     }
105  *   }
106  *
107  *   protected synchronized void scheduleNext() {
108  *     if ((active = tasks.poll()) != null) {
109  *       executor.execute(active);
110  *     }
111  *   }
112  * }}</pre>
113  *
114  * The {@code Executor} implementations provided in this package
115  * implement {@link ExecutorService}, which is a more extensive
116  * interface.  The {@link ThreadPoolExecutor} class provides an
117  * extensible thread pool implementation. The {@link Executors} class
118  * provides convenient factory methods for these Executors.
119  *
120  * <p>Memory consistency effects: Actions in a thread prior to
121  * submitting a {@code Runnable} object to an {@code Executor}
122  * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
123  * its execution begins, perhaps in another thread.
124  *
125  * @since 1.5
126  * @author Doug Lea
127  */
128 public interface Executor {
129 
130     /**
131      * Executes the given command at some time in the future.  The command
132      * may execute in a new thread, in a pooled thread, or in the calling
133      * thread, at the discretion of the {@code Executor} implementation.
134      *
135      * @param command the runnable task
136      * @throws RejectedExecutionException if this task cannot be
137      * accepted for execution
138      * @throws NullPointerException if command is null
139      */
140     void execute(Runnable command);
141 }