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