Source for java.util.concurrent.Executor

   1: /*
   2:  * Written by Doug Lea with assistance from members of JCP JSR-166
   3:  * Expert Group and released to the public domain, as explained at
   4:  * http://creativecommons.org/licenses/publicdomain
   5:  */
   6: 
   7: package java.util.concurrent;
   8: 
   9: /**
  10:  * An object that executes submitted {@link Runnable} tasks. This
  11:  * interface provides a way of decoupling task submission from the
  12:  * mechanics of how each task will be run, including details of thread
  13:  * use, scheduling, etc.  An <tt>Executor</tt> is normally used
  14:  * instead of explicitly creating threads. For example, rather than
  15:  * invoking <tt>new Thread(new(RunnableTask())).start()</tt> for each
  16:  * of a set of tasks, you might use:
  17:  *
  18:  * <pre>
  19:  * Executor executor = <em>anExecutor</em>;
  20:  * executor.execute(new RunnableTask1());
  21:  * executor.execute(new RunnableTask2());
  22:  * ...
  23:  * </pre>
  24:  *
  25:  * However, the <tt>Executor</tt> interface does not strictly
  26:  * require that execution be asynchronous. In the simplest case, an
  27:  * executor can run the submitted task immediately in the caller's
  28:  * thread:
  29:  *
  30:  * <pre>
  31:  * class DirectExecutor implements Executor {
  32:  *     public void execute(Runnable r) {
  33:  *         r.run();
  34:  *     }
  35:  * }</pre>
  36:  *
  37:  * More typically, tasks are executed in some thread other
  38:  * than the caller's thread.  The executor below spawns a new thread
  39:  * for each task.
  40:  *
  41:  * <pre>
  42:  * class ThreadPerTaskExecutor implements Executor {
  43:  *     public void execute(Runnable r) {
  44:  *         new Thread(r).start();
  45:  *     }
  46:  * }</pre>
  47:  *
  48:  * Many <tt>Executor</tt> implementations impose some sort of
  49:  * limitation on how and when tasks are scheduled.  The executor below
  50:  * serializes the submission of tasks to a second executor,
  51:  * illustrating a composite executor.
  52:  *
  53:  * <pre>
  54:  * class SerialExecutor implements Executor {
  55:  *     final Queue&lt;Runnable&gt; tasks = new ArrayDeque&lt;Runnable&gt;();
  56:  *     final Executor executor;
  57:  *     Runnable active;
  58:  *
  59:  *     SerialExecutor(Executor executor) {
  60:  *         this.executor = executor;
  61:  *     }
  62:  *
  63:  *     public synchronized void execute(final Runnable r) {
  64:  *         tasks.offer(new Runnable() {
  65:  *             public void run() {
  66:  *                 try {
  67:  *                     r.run();
  68:  *                 } finally {
  69:  *                     scheduleNext();
  70:  *                 }
  71:  *             }
  72:  *         });
  73:  *         if (active == null) {
  74:  *             scheduleNext();
  75:  *         }
  76:  *     }
  77:  *
  78:  *     protected synchronized void scheduleNext() {
  79:  *         if ((active = tasks.poll()) != null) {
  80:  *             executor.execute(active);
  81:  *         }
  82:  *     }
  83:  * }</pre>
  84:  *
  85:  * The <tt>Executor</tt> implementations provided in this package
  86:  * implement {@link ExecutorService}, which is a more extensive
  87:  * interface.  The {@link ThreadPoolExecutor} class provides an
  88:  * extensible thread pool implementation. The {@link Executors} class
  89:  * provides convenient factory methods for these Executors.
  90:  *
  91:  * <p>Memory consistency effects: Actions in a thread prior to
  92:  * submitting a {@code Runnable} object to an {@code Executor}
  93:  * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
  94:  * its execution begins, perhaps in another thread.
  95:  *
  96:  * @since 1.5
  97:  * @author Doug Lea
  98:  */
  99: public interface Executor {
 100: 
 101:     /**
 102:      * Executes the given command at some time in the future.  The command
 103:      * may execute in a new thread, in a pooled thread, or in the calling
 104:      * thread, at the discretion of the <tt>Executor</tt> implementation.
 105:      *
 106:      * @param command the runnable task
 107:      * @throws RejectedExecutionException if this task cannot be
 108:      * accepted for execution.
 109:      * @throws NullPointerException if command is null
 110:      */
 111:     void execute(Runnable command);
 112: }