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/publicdomain/zero/1.0/ 5 */ 6 7// BEGIN android-note 8// omit links to ForkJoinPool, ForkJoinTask, LinkedTransferQueue, Phaser, TransferQueue 9// END android-note 10 11/** 12 * Utility classes commonly useful in concurrent programming. This 13 * package includes a few small standardized extensible frameworks, as 14 * well as some classes that provide useful functionality and are 15 * otherwise tedious or difficult to implement. Here are brief 16 * descriptions of the main components. See also the 17 * {@link java.util.concurrent.locks} and 18 * {@link java.util.concurrent.atomic} packages. 19 * 20 * <h2>Executors</h2> 21 * 22 * <b>Interfaces.</b> 23 * 24 * {@link java.util.concurrent.Executor} is a simple standardized 25 * interface for defining custom thread-like subsystems, including 26 * thread pools, asynchronous I/O, and lightweight task frameworks. 27 * Depending on which concrete Executor class is being used, tasks may 28 * execute in a newly created thread, an existing task-execution thread, 29 * or the thread calling {@link java.util.concurrent.Executor#execute 30 * execute}, and may execute sequentially or concurrently. 31 * 32 * {@link java.util.concurrent.ExecutorService} provides a more 33 * complete asynchronous task execution framework. An 34 * ExecutorService manages queuing and scheduling of tasks, 35 * and allows controlled shutdown. 36 * 37 * The {@link java.util.concurrent.ScheduledExecutorService} 38 * subinterface and associated interfaces add support for 39 * delayed and periodic task execution. ExecutorServices 40 * provide methods arranging asynchronous execution of any 41 * function expressed as {@link java.util.concurrent.Callable}, 42 * the result-bearing analog of {@link java.lang.Runnable}. 43 * 44 * A {@link java.util.concurrent.Future} returns the results of 45 * a function, allows determination of whether execution has 46 * completed, and provides a means to cancel execution. 47 * 48 * A {@link java.util.concurrent.RunnableFuture} is a {@code Future} 49 * that possesses a {@code run} method that upon execution, 50 * sets its results. 51 * 52 * <p> 53 * 54 * <b>Implementations.</b> 55 * 56 * Classes {@link java.util.concurrent.ThreadPoolExecutor} and 57 * {@link java.util.concurrent.ScheduledThreadPoolExecutor} 58 * provide tunable, flexible thread pools. 59 * 60 * The {@link java.util.concurrent.Executors} class provides 61 * factory methods for the most common kinds and configurations 62 * of Executors, as well as a few utility methods for using 63 * them. Other utilities based on {@code Executors} include the 64 * concrete class {@link java.util.concurrent.FutureTask} 65 * providing a common extensible implementation of Futures, and 66 * {@link java.util.concurrent.ExecutorCompletionService}, that 67 * assists in coordinating the processing of groups of 68 * asynchronous tasks. 69 * 70 * <h2>Queues</h2> 71 * 72 * The {@link java.util.concurrent.ConcurrentLinkedQueue} class 73 * supplies an efficient scalable thread-safe non-blocking FIFO 74 * queue. 75 * 76 * <p>Five implementations in {@code java.util.concurrent} support 77 * the extended {@link java.util.concurrent.BlockingQueue} 78 * interface, that defines blocking versions of put and take: 79 * {@link java.util.concurrent.LinkedBlockingQueue}, 80 * {@link java.util.concurrent.ArrayBlockingQueue}, 81 * {@link java.util.concurrent.SynchronousQueue}, 82 * {@link java.util.concurrent.PriorityBlockingQueue}, and 83 * {@link java.util.concurrent.DelayQueue}. 84 * The different classes cover the most common usage contexts 85 * for producer-consumer, messaging, parallel tasking, and 86 * related concurrent designs. 87 * 88 * <p>The {@link java.util.concurrent.BlockingDeque} interface 89 * extends {@code BlockingQueue} to support both FIFO and LIFO 90 * (stack-based) operations. 91 * Class {@link java.util.concurrent.LinkedBlockingDeque} 92 * provides an implementation. 93 * 94 * <h2>Timing</h2> 95 * 96 * The {@link java.util.concurrent.TimeUnit} class provides 97 * multiple granularities (including nanoseconds) for 98 * specifying and controlling time-out based operations. Most 99 * classes in the package contain operations based on time-outs 100 * in addition to indefinite waits. In all cases that 101 * time-outs are used, the time-out specifies the minimum time 102 * that the method should wait before indicating that it 103 * timed-out. Implementations make a "best effort" 104 * to detect time-outs as soon as possible after they occur. 105 * However, an indefinite amount of time may elapse between a 106 * time-out being detected and a thread actually executing 107 * again after that time-out. All methods that accept timeout 108 * parameters treat values less than or equal to zero to mean 109 * not to wait at all. To wait "forever", you can use a value 110 * of {@code Long.MAX_VALUE}. 111 * 112 * <h2>Synchronizers</h2> 113 * 114 * Four classes aid common special-purpose synchronization idioms. 115 * <ul> 116 * 117 * <li>{@link java.util.concurrent.Semaphore} is a classic concurrency tool. 118 * 119 * <li>{@link java.util.concurrent.CountDownLatch} is a very simple yet 120 * very common utility for blocking until a given number of signals, 121 * events, or conditions hold. 122 * 123 * <li>A {@link java.util.concurrent.CyclicBarrier} is a resettable 124 * multiway synchronization point useful in some styles of parallel 125 * programming. 126 * 127 * <li>An {@link java.util.concurrent.Exchanger} allows two threads to 128 * exchange objects at a rendezvous point, and is useful in several 129 * pipeline designs. 130 * 131 * </ul> 132 * 133 * <h2>Concurrent Collections</h2> 134 * 135 * Besides Queues, this package supplies Collection implementations 136 * designed for use in multithreaded contexts: 137 * {@link java.util.concurrent.ConcurrentHashMap}, 138 * {@link java.util.concurrent.ConcurrentSkipListMap}, 139 * {@link java.util.concurrent.ConcurrentSkipListSet}, 140 * {@link java.util.concurrent.CopyOnWriteArrayList}, and 141 * {@link java.util.concurrent.CopyOnWriteArraySet}. 142 * When many threads are expected to access a given collection, a 143 * {@code ConcurrentHashMap} is normally preferable to a synchronized 144 * {@code HashMap}, and a {@code ConcurrentSkipListMap} is normally 145 * preferable to a synchronized {@code TreeMap}. 146 * A {@code CopyOnWriteArrayList} is preferable to a synchronized 147 * {@code ArrayList} when the expected number of reads and traversals 148 * greatly outnumber the number of updates to a list. 149 * 150 * <p>The "Concurrent" prefix used with some classes in this package 151 * is a shorthand indicating several differences from similar 152 * "synchronized" classes. For example {@code java.util.Hashtable} and 153 * {@code Collections.synchronizedMap(new HashMap())} are 154 * synchronized. But {@link 155 * java.util.concurrent.ConcurrentHashMap} is "concurrent". A 156 * concurrent collection is thread-safe, but not governed by a 157 * single exclusion lock. In the particular case of 158 * ConcurrentHashMap, it safely permits any number of 159 * concurrent reads as well as a tunable number of concurrent 160 * writes. "Synchronized" classes can be useful when you need 161 * to prevent all access to a collection via a single lock, at 162 * the expense of poorer scalability. In other cases in which 163 * multiple threads are expected to access a common collection, 164 * "concurrent" versions are normally preferable. And 165 * unsynchronized collections are preferable when either 166 * collections are unshared, or are accessible only when 167 * holding other locks. 168 * 169 * <p>Most concurrent Collection implementations (including most 170 * Queues) also differ from the usual java.util conventions in that 171 * their Iterators provide <em>weakly consistent</em> rather than 172 * fast-fail traversal. A weakly consistent iterator is thread-safe, 173 * but does not necessarily freeze the collection while iterating, so 174 * it may (or may not) reflect any updates since the iterator was 175 * created. 176 * 177 * <h2 id="MemoryVisibility">Memory Consistency Properties</h2> 178 * 179 * <a href="http://java.sun.com/docs/books/jls/third_edition/html/memory.html"> 180 * Chapter 17 of the Java Language Specification</a> defines the 181 * <i>happens-before</i> relation on memory operations such as reads and 182 * writes of shared variables. The results of a write by one thread are 183 * guaranteed to be visible to a read by another thread only if the write 184 * operation <i>happens-before</i> the read operation. The 185 * {@code synchronized} and {@code volatile} constructs, as well as the 186 * {@code Thread.start()} and {@code Thread.join()} methods, can form 187 * <i>happens-before</i> relationships. In particular: 188 * 189 * <ul> 190 * <li>Each action in a thread <i>happens-before</i> every action in that 191 * thread that comes later in the program's order. 192 * 193 * <li>An unlock ({@code synchronized} block or method exit) of a 194 * monitor <i>happens-before</i> every subsequent lock ({@code synchronized} 195 * block or method entry) of that same monitor. And because 196 * the <i>happens-before</i> relation is transitive, all actions 197 * of a thread prior to unlocking <i>happen-before</i> all actions 198 * subsequent to any thread locking that monitor. 199 * 200 * <li>A write to a {@code volatile} field <i>happens-before</i> every 201 * subsequent read of that same field. Writes and reads of 202 * {@code volatile} fields have similar memory consistency effects 203 * as entering and exiting monitors, but do <em>not</em> entail 204 * mutual exclusion locking. 205 * 206 * <li>A call to {@code start} on a thread <i>happens-before</i> any 207 * action in the started thread. 208 * 209 * <li>All actions in a thread <i>happen-before</i> any other thread 210 * successfully returns from a {@code join} on that thread. 211 * 212 * </ul> 213 * 214 * 215 * The methods of all classes in {@code java.util.concurrent} and its 216 * subpackages extend these guarantees to higher-level 217 * synchronization. In particular: 218 * 219 * <ul> 220 * 221 * <li>Actions in a thread prior to placing an object into any concurrent 222 * collection <i>happen-before</i> actions subsequent to the access or 223 * removal of that element from the collection in another thread. 224 * 225 * <li>Actions in a thread prior to the submission of a {@code Runnable} 226 * to an {@code Executor} <i>happen-before</i> its execution begins. 227 * Similarly for {@code Callables} submitted to an {@code ExecutorService}. 228 * 229 * <li>Actions taken by the asynchronous computation represented by a 230 * {@code Future} <i>happen-before</i> actions subsequent to the 231 * retrieval of the result via {@code Future.get()} in another thread. 232 * 233 * <li>Actions prior to "releasing" synchronizer methods such as 234 * {@code Lock.unlock}, {@code Semaphore.release}, and 235 * {@code CountDownLatch.countDown} <i>happen-before</i> actions 236 * subsequent to a successful "acquiring" method such as 237 * {@code Lock.lock}, {@code Semaphore.acquire}, 238 * {@code Condition.await}, and {@code CountDownLatch.await} on the 239 * same synchronizer object in another thread. 240 * 241 * <li>For each pair of threads that successfully exchange objects via 242 * an {@code Exchanger}, actions prior to the {@code exchange()} 243 * in each thread <i>happen-before</i> those subsequent to the 244 * corresponding {@code exchange()} in another thread. 245 * 246 * <li>Actions prior to calling {@code CyclicBarrier.await} 247 * <i>happen-before</i> actions performed by the barrier action, and 248 * actions performed by the barrier action <i>happen-before</i> actions 249 * subsequent to a successful return from the corresponding {@code await} 250 * in other threads. 251 * 252 * </ul> 253 * 254 * @since 1.5 255 */ 256package java.util.concurrent; 257