jaroslav@1258: /* jaroslav@1258: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. jaroslav@1258: * jaroslav@1258: * This code is free software; you can redistribute it and/or modify it jaroslav@1258: * under the terms of the GNU General Public License version 2 only, as jaroslav@1258: * published by the Free Software Foundation. Oracle designates this jaroslav@1258: * particular file as subject to the "Classpath" exception as provided jaroslav@1258: * by Oracle in the LICENSE file that accompanied this code. jaroslav@1258: * jaroslav@1258: * This code is distributed in the hope that it will be useful, but WITHOUT jaroslav@1258: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or jaroslav@1258: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License jaroslav@1258: * version 2 for more details (a copy is included in the LICENSE file that jaroslav@1258: * accompanied this code). jaroslav@1258: * jaroslav@1258: * You should have received a copy of the GNU General Public License version jaroslav@1258: * 2 along with this work; if not, write to the Free Software Foundation, jaroslav@1258: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. jaroslav@1258: * jaroslav@1258: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA jaroslav@1258: * or visit www.oracle.com if you need additional information or have any jaroslav@1258: * questions. jaroslav@1258: */ jaroslav@1258: jaroslav@1258: /* jaroslav@1258: * This file is available under and governed by the GNU General Public jaroslav@1258: * License version 2 only, as published by the Free Software Foundation. jaroslav@1258: * However, the following notice accompanied the original version of this jaroslav@1258: * file: jaroslav@1258: * jaroslav@1258: * Written by Doug Lea with assistance from members of JCP JSR-166 jaroslav@1258: * Expert Group and released to the public domain, as explained at jaroslav@1258: * http://creativecommons.org/publicdomain/zero/1.0/ jaroslav@1258: */ jaroslav@1258: jaroslav@1258: package java.util.concurrent; jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * An object that executes submitted {@link Runnable} tasks. This jaroslav@1258: * interface provides a way of decoupling task submission from the jaroslav@1258: * mechanics of how each task will be run, including details of thread jaroslav@1258: * use, scheduling, etc. An Executor is normally used jaroslav@1258: * instead of explicitly creating threads. For example, rather than jaroslav@1258: * invoking new Thread(new(RunnableTask())).start() for each jaroslav@1258: * of a set of tasks, you might use: jaroslav@1258: * jaroslav@1258: * 
jaroslav@1258:  * Executor executor = anExecutor;
jaroslav@1258:  * executor.execute(new RunnableTask1());
jaroslav@1258:  * executor.execute(new RunnableTask2());
jaroslav@1258:  * ...
jaroslav@1258:  *
jaroslav@1258: * jaroslav@1258: * However, the Executor interface does not strictly jaroslav@1258: * require that execution be asynchronous. In the simplest case, an jaroslav@1258: * executor can run the submitted task immediately in the caller's jaroslav@1258: * thread: jaroslav@1258: * jaroslav@1258: * 
jaroslav@1258:  * class DirectExecutor implements Executor {
jaroslav@1258:  *     public void execute(Runnable r) {
jaroslav@1258:  *         r.run();
jaroslav@1258:  *     }
jaroslav@1258:  * }
jaroslav@1258: * jaroslav@1258: * More typically, tasks are executed in some thread other jaroslav@1258: * than the caller's thread. The executor below spawns a new thread jaroslav@1258: * for each task. jaroslav@1258: * jaroslav@1258: * 
jaroslav@1258:  * class ThreadPerTaskExecutor implements Executor {
jaroslav@1258:  *     public void execute(Runnable r) {
jaroslav@1258:  *         new Thread(r).start();
jaroslav@1258:  *     }
jaroslav@1258:  * }
jaroslav@1258: * jaroslav@1258: * Many Executor implementations impose some sort of jaroslav@1258: * limitation on how and when tasks are scheduled. The executor below jaroslav@1258: * serializes the submission of tasks to a second executor, jaroslav@1258: * illustrating a composite executor. jaroslav@1258: * jaroslav@1258: * 
 {@code
jaroslav@1258:  * class SerialExecutor implements Executor {
jaroslav@1258:  *   final Queue tasks = new ArrayDeque();
jaroslav@1258:  *   final Executor executor;
jaroslav@1258:  *   Runnable active;
jaroslav@1258:  *
jaroslav@1258:  *   SerialExecutor(Executor executor) {
jaroslav@1258:  *     this.executor = executor;
jaroslav@1258:  *   }
jaroslav@1258:  *
jaroslav@1258:  *   public synchronized void execute(final Runnable r) {
jaroslav@1258:  *     tasks.offer(new Runnable() {
jaroslav@1258:  *       public void run() {
jaroslav@1258:  *         try {
jaroslav@1258:  *           r.run();
jaroslav@1258:  *         } finally {
jaroslav@1258:  *           scheduleNext();
jaroslav@1258:  *         }
jaroslav@1258:  *       }
jaroslav@1258:  *     });
jaroslav@1258:  *     if (active == null) {
jaroslav@1258:  *       scheduleNext();
jaroslav@1258:  *     }
jaroslav@1258:  *   }
jaroslav@1258:  *
jaroslav@1258:  *   protected synchronized void scheduleNext() {
jaroslav@1258:  *     if ((active = tasks.poll()) != null) {
jaroslav@1258:  *       executor.execute(active);
jaroslav@1258:  *     }
jaroslav@1258:  *   }
jaroslav@1258:  * }}
jaroslav@1258: * jaroslav@1258: * The Executor implementations provided in this package jaroslav@1258: * implement {@link ExecutorService}, which is a more extensive jaroslav@1258: * interface. The {@link ThreadPoolExecutor} class provides an jaroslav@1258: * extensible thread pool implementation. The {@link Executors} class jaroslav@1258: * provides convenient factory methods for these Executors. jaroslav@1258: * jaroslav@1258: *

Memory consistency effects: Actions in a thread prior to jaroslav@1258: * submitting a {@code Runnable} object to an {@code Executor} jaroslav@1258: * happen-before jaroslav@1258: * its execution begins, perhaps in another thread. jaroslav@1258: * jaroslav@1258: * @since 1.5 jaroslav@1258: * @author Doug Lea jaroslav@1258: */ jaroslav@1258: public interface Executor { jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Executes the given command at some time in the future. The command jaroslav@1258: * may execute in a new thread, in a pooled thread, or in the calling jaroslav@1258: * thread, at the discretion of the Executor implementation. jaroslav@1258: * jaroslav@1258: * @param command the runnable task jaroslav@1258: * @throws RejectedExecutionException if this task cannot be jaroslav@1258: * accepted for execution. jaroslav@1258: * @throws NullPointerException if command is null jaroslav@1258: */ jaroslav@1258: void execute(Runnable command); jaroslav@1258: }