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

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