Home » openjdk-7 » java » util » concurrent » [javadoc | source]

    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 <tt>Executor</tt> is normally used
   43    * instead of explicitly creating threads. For example, rather than
   44    * invoking <tt>new Thread(new(RunnableTask())).start()</tt> 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 <tt>Executor</tt> 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>
   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>
   71    * class ThreadPerTaskExecutor implements Executor {
   72    *     public void execute(Runnable r) {
   73    *         new Thread(r).start();
   74    *     }
   75    * }</pre>
   76    *
   77    * Many <tt>Executor</tt> 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 <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   }

Home » openjdk-7 » java » util » concurrent » [javadoc | source]