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