1adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/* 2adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Written by Doug Lea with assistance from members of JCP JSR-166 3adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Expert Group and released to the public domain, as explained at 4a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * http://creativecommons.org/publicdomain/zero/1.0/ 5adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 6adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 7adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpackage java.util.concurrent; 8adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 9adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/** 10adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * An object that executes submitted {@link Runnable} tasks. This 11adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * interface provides a way of decoupling task submission from the 12adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * mechanics of how each task will be run, including details of thread 1391770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * use, scheduling, etc. An {@code Executor} is normally used 14adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * instead of explicitly creating threads. For example, rather than 1591770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * invoking {@code new Thread(new(RunnableTask())).start()} for each 16adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * of a set of tasks, you might use: 17adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 18adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <pre> 19adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Executor executor = <em>anExecutor</em>; 20adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * executor.execute(new RunnableTask1()); 21adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * executor.execute(new RunnableTask2()); 22adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * ... 23adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </pre> 24bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 2591770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * However, the {@code Executor} interface does not strictly 26adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * require that execution be asynchronous. In the simplest case, an 27adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * executor can run the submitted task immediately in the caller's 28adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * thread: 29adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 30a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * <pre> {@code 31adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * class DirectExecutor implements Executor { 32a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * public void execute(Runnable r) { 33a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * r.run(); 34a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * } 35a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * }}</pre> 36adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 37adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * More typically, tasks are executed in some thread other 38adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * than the caller's thread. The executor below spawns a new thread 39adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * for each task. 40adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 41a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * <pre> {@code 42adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * class ThreadPerTaskExecutor implements Executor { 43a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * public void execute(Runnable r) { 44a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * new Thread(r).start(); 45a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * } 46a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * }}</pre> 47adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 4891770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * Many {@code Executor} implementations impose some sort of 49adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * limitation on how and when tasks are scheduled. The executor below 50adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * serializes the submission of tasks to a second executor, 51adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * illustrating a composite executor. 52adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 538eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * <pre> {@code 54adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * class SerialExecutor implements Executor { 558eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * final Queue<Runnable> tasks = new ArrayDeque<Runnable>(); 568eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * final Executor executor; 578eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * Runnable active; 58adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 598eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * SerialExecutor(Executor executor) { 608eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * this.executor = executor; 618eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * } 62adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 638eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * public synchronized void execute(final Runnable r) { 648eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * tasks.offer(new Runnable() { 658eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * public void run() { 668eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * try { 678eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * r.run(); 688eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * } finally { 698eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * scheduleNext(); 70adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 718eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * } 728eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * }); 738eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * if (active == null) { 748eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * scheduleNext(); 75adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 768eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * } 77adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 788eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * protected synchronized void scheduleNext() { 798eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * if ((active = tasks.poll()) != null) { 808eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * executor.execute(active); 81adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * } 828eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * } 838eb35c835be1345d3873a82cc9e42f944d698afdJesse Wilson * }}</pre> 84adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 8591770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * The {@code Executor} implementations provided in this package 86adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * implement {@link ExecutorService}, which is a more extensive 87adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * interface. The {@link ThreadPoolExecutor} class provides an 88adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * extensible thread pool implementation. The {@link Executors} class 89adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * provides convenient factory methods for these Executors. 90adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 91bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * <p>Memory consistency effects: Actions in a thread prior to 92bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * submitting a {@code Runnable} object to an {@code Executor} 93bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a> 94bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * its execution begins, perhaps in another thread. 95bba8d1acd6dfff06c94d761c67a30154ca5ca5dfJesse Wilson * 96adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @since 1.5 97adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @author Doug Lea 98adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 99adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpublic interface Executor { 100adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 101adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 102adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Executes the given command at some time in the future. The command 103adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * may execute in a new thread, in a pooled thread, or in the calling 10491770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * thread, at the discretion of the {@code Executor} implementation. 105adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 106adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param command the runnable task 107adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws RejectedExecutionException if this task cannot be 10891770798d8b9280d48d30df2ed7f63b3ed9b036fCalin Juravle * accepted for execution 109adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws NullPointerException if command is null 110adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 111adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project void execute(Runnable command); 112adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project} 113