001 /*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
003 *
004 * This code is free software; you can redistribute it and/or modify it
005 * under the terms of the GNU General Public License version 2 only, as
006 * published by the Free Software Foundation. Sun designates this
007 * particular file as subject to the "Classpath" exception as provided
008 * by Sun in the LICENSE file that accompanied this code.
009 *
010 * This code is distributed in the hope that it will be useful, but WITHOUT
011 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
012 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
013 * version 2 for more details (a copy is included in the LICENSE file that
014 * accompanied this code).
015 *
016 * You should have received a copy of the GNU General Public License version
017 * 2 along with this work; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
019 *
020 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
021 * CA 95054 USA or visit www.sun.com if you need additional information or
022 * have any questions.
023 */
024
025 /*
026 * This file is available under and governed by the GNU General Public
027 * License version 2 only, as published by the Free Software Foundation.
028 * However, the following notice accompanied the original version of this
029 * file:
030 *
031 * Written by Doug Lea with assistance from members of JCP JSR-166
032 * Expert Group and released to the public domain, as explained at
033 * http://creativecommons.org/licenses/publicdomain
034 */
035
036 package java.util.concurrent;
037
038 /**
039 * An object that executes submitted {@link Runnable} tasks. This
040 * interface provides a way of decoupling task submission from the
041 * mechanics of how each task will be run, including details of thread
042 * use, scheduling, etc. An <tt>Executor</tt> is normally used
043 * instead of explicitly creating threads. For example, rather than
044 * invoking <tt>new Thread(new(RunnableTask())).start()</tt> for each
045 * of a set of tasks, you might use:
046 *
047 * <pre>
048 * Executor executor = <em>anExecutor</em>;
049 * executor.execute(new RunnableTask1());
050 * executor.execute(new RunnableTask2());
051 * ...
052 * </pre>
053 *
054 * However, the <tt>Executor</tt> interface does not strictly
055 * require that execution be asynchronous. In the simplest case, an
056 * executor can run the submitted task immediately in the caller's
057 * thread:
058 *
059 * <pre>
060 * class DirectExecutor implements Executor {
061 * public void execute(Runnable r) {
062 * r.run();
063 * }
064 * }</pre>
065 *
066 * More typically, tasks are executed in some thread other
067 * than the caller's thread. The executor below spawns a new thread
068 * for each task.
069 *
070 * <pre>
071 * class ThreadPerTaskExecutor implements Executor {
072 * public void execute(Runnable r) {
073 * new Thread(r).start();
074 * }
075 * }</pre>
076 *
077 * Many <tt>Executor</tt> implementations impose some sort of
078 * limitation on how and when tasks are scheduled. The executor below
079 * serializes the submission of tasks to a second executor,
080 * illustrating a composite executor.
081 *
082 * <pre>
083 * class SerialExecutor implements Executor {
084 * final Queue<Runnable> tasks = new ArrayDeque<Runnable>();
085 * final Executor executor;
086 * Runnable active;
087 *
088 * SerialExecutor(Executor executor) {
089 * this.executor = executor;
090 * }
091 *
092 * public synchronized void execute(final Runnable r) {
093 * tasks.offer(new Runnable() {
094 * public void run() {
095 * try {
096 * r.run();
097 * } finally {
098 * scheduleNext();
099 * }
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 <tt>Executor</tt> 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 <tt>Executor</tt> 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 }
|